Skip to main content
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

​
X-OTAS-USER-TOKEN
string
required
JWT obtained from the OTAS login endpoint, identifying the calling user.
​
X-OTAS-PROJECT-ID
string
required
UUID of the project the agent belongs to.

​
Request body

​
agent_id
string
required
UUID of the agent for which to rotate the key.

​
Response

​
status
number
1 on success.
​
status_description
string
"agent_key_created" on success.
​
response
object
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

Statusstatus_descriptionCause
403forbiddenCaller does not have Admin privilege on the project.
404agent_not_found_or_invalid_idNo active agent with that UUID exists in the project, or the UUID is malformed.
400agent_id_requiredThe 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
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us