# Create an API key

Mint a new API key on behalf of a user — for example, to set up a SAP or HRIS integration.

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

```bash
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.

```json
{
  "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. |