Skip to main content
POST
Create a credential

Authorizations

Authorization
string
header
required

User session JWT (Bearer ). Must be paired with the X-Team-ID request header on team-scoped endpoints so the server knows which team's resources to operate on.

Headers

X-Team-ID
string<uuid>
required

UUID of the team to scope the request to. Required on all team-scoped JWT endpoints because a user may belong to multiple teams.

Example:

"019abc12-4567-7890-abcd-ef1234567891"

Body

application/json
kind
enum<string>
required

Subset of CredentialKind permitted in POST /credentials. Excludes device because dk- credentials must come from /desktop/pair/confirm (which binds the credential to the confirming user's JWT). Direct POST /credentials { kind: "device" } is rejected by the service layer even if a client sends it.

Available options:
integration,
agent
Example:

"integration"

display_name
string
required

Human-readable label for the credential (shown back in the list view).

Required string length: 1 - 100
Example:

"CI bot"

expires_in_days
integer

Optional expiry, in days from creation. Integer between 1 and 365 inclusive. If omitted, the credential never expires until manually revoked.

Required range: 1 <= x <= 365
Example:

90

Response

Credential created

id
string<uuid>
required

UUID of the credential row.

kind
enum<string>
required

Type of credential. Each kind shares the same storage shape but has different behaviour:

  • integration (sk-...): team-scoped programmatic key. Carries no user identity; used by CI bots, third-party integrations, scripts.
  • agent (ak-...): team-scoped agent key. Used by headless workers connecting to the platform's WebSocket. Rejected by the REST surface — see the carrier table at the top of the spec.
  • device (dk-...): per-user, team-scoped key issued by the desktop device-pairing flow (POST /desktop/pair/confirm). Carries user_id so the authorization layer can run against the actual user. Cannot be issued via POST /credentials — use the pairing flow.
Available options:
integration,
agent,
device
Example:

"integration"

key_prefix
string
required

The first 12 characters of the raw key, e.g. "sk-abcd1234..".

Example:

"sk-abcd1234"

raw_key
string
required

The full secret. Shown only once — store it securely; subsequent list responses only show the prefix.

Example:

"sk-abcdefghijklmnop..."