Create an API key

Creates a new API key for a user. The plaintext key is returned exactly once in this response — store it securely. The key inherits the target user’s role and organization memberships.

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable label (max 255 chars).
userId	string	Yes	ID of the user the key acts as. Must exist.
expiresInDays	integer	No	Days until expiry. Default 90, range 1–365.

Example request

curl -X POST https://app.talent-ray.com/api/admin/api-keys \
  -H "Authorization: Bearer tr_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Karaca SAP nightly sync",
    "userId": "user_abc123",
    "expiresInDays": 30
  }'

Response

200 OK — the key field is shown only here and never again.

{
  "success": true,
  "data": {
    "id": "apikey_xyz789",
    "name": "Karaca SAP nightly sync",
    "key": "tr_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "prefix": "tr_",
    "start": "tr_aaaa",
    "expiresAt": "2026-09-03T12:00:00Z",
    "userId": "user_abc123"
  }
}

Field	Type	Description
id	string	The key’s ID — use it to revoke or audit the key.
key	string	The plaintext key. Shown once.
prefix	string	Always tr_.
start	string	First characters, for display.
expiresAt	string	ISO 8601 expiry timestamp.
userId	string	The owner the key acts as.

Status codes

Status	Meaning
200	Key created.
400	Validation error (missing name/userId, bad expiresInDays).
401	No valid API key.
403	Caller is not an admin.
404	userId not found.
429	Rate limited.