Clerk API (unofficial showcase)
POST/api_keys

Create an API key

Creates an API key for the specified subject. Supply name and subject, and provide optional claims, scopes, creator, and expiration settings as needed. The response includes the key secret, so handle it as a credential.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields

API key settings. name and subject are required.

typestringoptional
The API key type. Must contain between 3 and 25 characters; defaults to `api_key` when omitted.
Default:api_key
namestringrequired
The API key name. Must contain at least 3 characters and have no leading or trailing whitespace.
descriptionstringoptional
A description of the API key. Maximum 255 characters.
subjectstringrequired
The subject identifier for the API key. Must use the `user_`, `org_`, `mch_`, or `scim_` prefix followed by 27 word characters.
claimsunknownoptional
Claims to associate with the API key; the schema does not specify a shape.
scopesarray<string>optional
The scopes to assign to the API key. Defaults to an empty array when omitted.
Default:[]
created_bystringoptional
The user identifier of the API key creator. Must use the `user_` prefix followed by 27 word characters.
seconds_until_expirationnumberoptional
The API key lifetime in seconds. Must be greater than 0.

3 status codes
200Returns the created API key object, including its identifier, configuration, and secret. Handle the secret as a credential.
objectstringrequired
Allowed:api_key
idstringrequired
typestringrequired
subjectstringrequired
namestringrequired
descriptionstringoptional
claimsunknownrequired
scopesarray<string>required
secretstringrequired
revokedbooleanrequired
revocation_reasonstringrequired
expiredbooleanrequired
expirationnumberrequired
The timestamp for when the API key will expire, in milliseconds
created_bystringrequired
last_used_atnumberrequired
The timestamp for when the API key was last used, in milliseconds
created_atnumberrequired
The timestamp for when the API key was created, in milliseconds
updated_atnumberrequired
The timestamp for when the API key was last updated, in milliseconds
400Returned when the request is invalid.
errorsarray<object>required
409Returned when the request conflicts with the current state.
errorsarray<object>required

Error handling

A 400 indicates invalid request data; a 409 indicates a conflict. name and subject are required; name must contain at least 3 characters and have no leading or trailing whitespace, and subject must match the user_, org_, mch_, or scim_ identifier format followed by 27 word characters. type must contain 3 to 25 characters, description must not exceed 255 characters, created_by must match the user_ identifier format followed by 27 word characters, and seconds_until_expiration must be greater than 0.