Skip to content
Chronary Docs

API Keys

Agent-scoped API keys (chr_ak_*) let you limit access to a single agent’s calendars, events, availability, and iCal subscriptions.

Create an agent-scoped key

Section titled “Create an agent-scoped key”
POST /v1/keys

Request body

Section titled “Request body”

| Field | Type | Required | Description | |-------|------|----------|-------------| | agent_id | string | Yes | Target agent ID (agt_*) | | label | string | No | Optional label, 1-100 characters |

Example

Section titled “Example”
Terminal window
curl -X POST https://api.chronary.ai/v1/keys \
  -H "Authorization: Bearer chr_sk_your_org_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_a1b2c3d4",
    "label": "Sales agent key"
  }'

Response 201 Created

Section titled “Response 201 Created”
{
  "id": "key_abc123",
  "key": "chr_ak_0123456789ABCDEF",
  "key_prefix": "chr_ak_0A1B2C3D",
  "agent_id": "agt_a1b2c3d4",
  "label": "Sales agent key",
  "created_at": "2026-04-17T16:20:00.000Z"
}

The raw key is returned only once. Store it immediately.

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 400 | validation_error | Invalid request body | | 403 | forbidden | Agent-scoped keys cannot manage org-level keys | | 404 | not_found | Agent not found |

List agent-scoped keys

Section titled “List agent-scoped keys”
GET /v1/keys

No query parameters are required.

Example

Section titled “Example”
Terminal window
curl https://api.chronary.ai/v1/keys \
  -H "Authorization: Bearer chr_sk_your_org_key"

Response 200 OK

Section titled “Response 200 OK”
{
  "keys": [
    {
      "id": "key_abc123",
      "key_prefix": "chr_ak_0A1B2C3D",
      "agent_id": "agt_a1b2c3d4",
      "label": "Sales agent key",
      "created_at": "2026-04-17T16:20:00.000Z"
    }
  ]
}

The raw secret value is not returned from list responses.

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 403 | forbidden | Agent-scoped keys cannot manage org-level keys |

Revoke an agent-scoped key

Section titled “Revoke an agent-scoped key”
DELETE /v1/keys/:id

Revokes the key immediately and returns 204 No Content.

Example

Section titled “Example”
Terminal window
curl -X DELETE https://api.chronary.ai/v1/keys/key_abc123 \
  -H "Authorization: Bearer chr_sk_your_org_key"

Errors

Section titled “Errors”

| Status | Type | Cause | |--------|------|-------| | 403 | forbidden | Agent-scoped keys cannot manage org-level keys | | 404 | not_found | Scoped key not found |