Create API Key

POST /api/api-keys

Create a new API key for the authenticated user in the active tenant. The plaintext key is returned only once in the response — store it securely.

Auth: Required — MANAGE_API_KEYS permission

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable label for the key (max 255 characters)
`permissions`	string[]	Yes	List of permission names to grant (minimum 1). Must be a subset of the creator's own permissions
`expiresAt`	string	No	ISO 8601 expiration date. Key is automatically rejected after this date

Example

curl -X POST https://api.reten.ai/api/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "permissions": ["manage_commerces", "view_activities"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/api-keys',
  {
    name: 'CI/CD Pipeline Key',
    permissions: ['manage_commerces', 'view_activities'],
    expiresAt: '2026-12-31T23:59:59Z',
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const { plaintextKey, id } = response.data;

Response `201 Created`

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "CI/CD Pipeline Key",
  "keyPrefix": "rtn_sk_a1b2c3d4",
  "plaintextKey": "rtn_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "isActive": true,
  "permissions": ["manage_commerces", "view_activities"],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "lastUsedAt": null,
  "createdAt": "2026-02-26T14:30:00.000Z",
  "revokedAt": null
}

The plaintextKey field is only included in the creation response. It cannot be retrieved again — if lost, revoke the key and create a new one.

Error Responses

Status	Description
`400`	Validation error — missing fields, empty permissions array, or invalid permission names
`401`	Missing or invalid authentication token
`403`	Requested permissions are not a subset of the creator's own permissions