Update API Key Permissions

PUT /api/api-keys/:id/permissions

Replace the full permission set of an API key owned by the authenticated user. The response has the same shape as an item of List API Keys — plaintextKey is never included. The secret does not change: the same x-api-key authenticates with the new set on the next request. The new set must be a subset of your current permissions, and api-key:manage cannot be assigned.

Auth: Required — api-key:manage permission

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the API key to update

Request Body

Field	Type	Required	Description
`permissions`	string[]	Yes	New list of permission names (minimum 1, no duplicates). Replaces the current set entirely

Example

curl -X PUT https://api.reten.ai/api/api-keys/f47ac10b-58cc-4372-a567-0e02b2c3d479/permissions \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["activity:view", "activity-result:submit"]
  }'

const keyId = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
const response = await fetch(`https://api.reten.ai/api/api-keys/${keyId}/permissions`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ permissions: ["activity:view", "activity-result:submit"] }),
});
const data = await response.json();

import requests

key_id = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
response = requests.put(
    f"https://api.reten.ai/api/api-keys/{key_id}/permissions",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={"permissions": ["activity:view", "activity-result:submit"]},
)
data = response.json()

Response `200 OK`

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "CI/CD Pipeline Key",
  "keyPrefix": "rtn_sk_a1b2c3d4",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "isActive": true,
  "permissions": ["activity:view", "activity-result:submit"],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "lastUsedAt": "2026-02-26T16:45:00.000Z",
  "createdAt": "2026-02-26T14:30:00.000Z",
  "revokedAt": null
}

Error Responses

Status	Description
`400`	Validation error — empty permissions array, duplicate permissions, a permission name outside the catalog, or an `id` that is not a UUID
`400`	API key is already revoked
`400`	No active tenant context
`401`	Missing or invalid authentication token
`403`	API key does not belong to the authenticated user or tenant — `You do not own this API key`
`403`	The requested set includes a permission you do not currently hold — `Cannot assign permissions you do not have: …`
`403`	The requested set includes `api-key:manage` — `Cannot assign api-key:manage to an API key`
`404`	API key not found