---
title: "Create Api Credential"
method: POST
path: "/api-credentials"
tags: ["ApiCredentials"]
---

# Create Api Credential

`POST /api-credentials`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/api-credentials`
- Auth: HTTP bearer

Create a server-to-server credential for the acting entity (or an
organization the caller can edit). The response includes client_secret
exactly once — secrets are hashed at rest and cannot be re-read; use
rotate to obtain a new one. Two ways to hold a token: exchange the
secret at POST /oauth/token (grant_type=client_credentials, 15-day
tokens), or mint a long-lived token in the UI with
POST /api-credentials/{id}/tokens (show-once token string, no secret
needed). Either way tokens act strictly for the owning entity at
edit-level authority.

## Request body

- ApiCredentialCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Relationships are resource identifier objects ({ id, type }). Equivalent JSON:API shape: ApiCredentialCreateModel.
  - `data` object
    - `name` string
    - `scopes` string
    - `owner` object, nullable: Owning entity — a User or an Organization the caller can edit. Defaults to the acting entity when omitted.
      - `id` string
      - `type` 'user' | 'organization'

## Response `201`

Created — includes client_secret (show-once).

- ApiCredentialsShowResponseAttributes
  - `data` ApiCredentialModelAttributes: Single API credential in attributes-adapter shape (Accept application/json): id, type and attribute fields at top level.
    - `id` string: The OAuth client_id (application uid).
    - `type` string
    - `name` string
    - `scopes` string
    - `owner_type` 'User' | 'Organization'
    - `owner_id` string, uuid
    - `created_at` string, date-time
    - `client_secret` string: Present ONLY in create and rotate responses (show-once).

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/4bedbc1c784c?raw)