POST /api/agent/v1/agents/key/create/

Use this endpoint to rotate an agent’s API key. It atomically revokes all currently active keys for the specified agent and issues a single fresh key with a new 30-day expiry. Rotate keys on a regular schedule or immediately if you suspect a key has been compromised. After rotation, update any service or environment that was using the old key — existing sessions started with a revoked key will continue to function until their session JWTs expire, but no new sessions can be created with the old key.

Only users with Admin privilege (privilege=1) on the project can create or rotate keys.

Endpoint

POST /api/agent/v1/agents/key/create/

Base URL: http://localhost:8000

Request headers

string

required

JWT obtained from the OTAS login endpoint, identifying the calling user.

string

required

UUID of the project the agent belongs to.

Request body

string

required

UUID of the agent for which to rotate the key.

Response

number

1 on success.

string

"agent_key_created" on success.

object

Hide properties

string

UUID of the agent whose key was rotated.

object

Hide properties

string

UUID of the newly created AgentKey record.

string

Short prefix used during key lookup.

string

Full API key in the format agent_<prefix>_<secret>. Shown only once.

string

ISO 8601 timestamp of key creation.

string

ISO 8601 timestamp — 30 days after created_at.

boolean

true immediately after creation.

The full api_key value is returned only in this response. All previously active keys for the agent are revoked before the new one is issued. Save the new key to a secrets manager or environment variable immediately — it cannot be retrieved again.

Revoking a specific key without rotation

If you need to revoke a single key without issuing a replacement, use:

POST /api/agent/v1/agents/key/revoke/

Request body:

{
  "agent_key_id": "<uuid-of-the-key-to-revoke>"
}

This requires the same X-OTAS-USER-TOKEN and X-OTAS-PROJECT-ID headers and Admin privilege. It sets the key as inactive immediately without creating a new key.

Errors

Status	`status_description`	Cause
403	`forbidden`	Caller does not have Admin privilege on the project.
404	`agent_not_found_or_invalid_id`	No active agent with that UUID exists in the project, or the UUID is malformed.
400	`agent_id_required`	The `agent_id` field was missing from the request body.

Example

cURL

curl --request POST \
  --url http://localhost:8000/api/agent/v1/agents/key/create/ \
  --header "X-OTAS-USER-TOKEN: <your-user-jwt>" \
  --header "X-OTAS-PROJECT-ID: 4b7e2f1a-9c3d-4e8b-a012-3f5d6e7c8b9a" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
  }'

Response (201)

{
  "status": 1,
  "status_description": "agent_key_created",
  "response": {
    "agent_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "agent_key": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "prefix": "aB3cD4eF",
      "api_key": "agent_aB3cD4eF_n3wS3cr3tT0k3nV4lueG0esH3re...",
      "created_at": "2026-04-16T12:00:00.000000+00:00",
      "expires_at": "2026-05-16T12:00:00.000000+00:00",
      "active": true
    }
  }
}

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

POST /api/agent/v1/agents/key/create/

Endpoint

Request headers

Request body

Response

Revoking a specific key without rotation

Errors

Example

​Endpoint

​Request headers

​Request body

​Response

​Revoking a specific key without rotation

​Errors

​Example

Endpoint

Request headers

Request body

Response

Revoking a specific key without rotation

Errors

Example