Authentication

Every API and MCP request requires an API key passed in the Authorization header.

API key format

# Org-level key
Authorization: Bearer chr_sk_a1b2c3d4e5f6...

# Agent-scoped key
Authorization: Bearer chr_ak_a1b2c3d4e5f6...

Chronary supports two key types:

| Key type | Prefix | Scope | |----------|--------|-------| | Org key | chr_sk_* | Full organization access | | Agent key | chr_ak_* | One agent’s calendars, events, availability, and iCal subscriptions |

Getting your keys

1. Sign up at console.chronary.ai
2. Your dashboard shows your org key
3. Use an org key to create agent-scoped keys with POST /v1/keys
4. Copy the raw key when it is created because it is only shown in full once

Caution

API keys are stored as irreversible SHA-256 hashes. If you lose a key, regenerate the org key from the console or create a new agent key. Revoked keys stop working immediately.

Managing agent-scoped keys

Only org-level keys can create, list, or revoke agent keys. The management surface is Bearer-authenticated under /v1/keys.

Create

curl https://api.chronary.ai/v1/keys \
  -X POST \
  -H "Authorization: Bearer chr_sk_your_org_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "label": "Sales agent production key"
  }'

List

curl https://api.chronary.ai/v1/keys \
  -H "Authorization: Bearer chr_sk_your_org_key"

Delete

curl https://api.chronary.ai/v1/keys/key_abc123 \
  -X DELETE \
  -H "Authorization: Bearer chr_sk_your_org_key"

Agent keys are read/write for that agent’s resources, but they cannot access org-only surfaces such as agent creation, cross-agent availability, webhooks, usage, or scheduling.

Using your key

curl

# Org key
curl https://api.chronary.ai/v1/agents \
  -H "Authorization: Bearer chr_sk_your_key_here"

# Agent key
curl https://api.chronary.ai/v1/agents/agt_abc123/availability \
  -H "Authorization: Bearer chr_ak_your_key_here"

JavaScript

const API_KEY = process.env.CHRONARY_API_KEY; // org or agent key

const response = await fetch('https://api.chronary.ai/v1/agents', {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

Python

from chronary import Chronary

# Reads CHRONARY_API_KEY from environment automatically
client = Chronary()

# Or pass the key explicitly
client = Chronary(api_key="chr_sk_your_key_here")

agents = client.agents.list()

CLI authentication

The Chronary CLI stores credentials locally so you don’t need to pass your key on every command.

Login

chronary auth login

The CLI prompts for your key, validates it against the API, and saves it to ~/.config/chronary/config.json.

Multiple profiles

Keep separate profiles for different environments or accounts:

# Login to a named profile
chronary auth login --profile production

# Switch between profiles
chronary auth switch production

# List all profiles
chronary auth list

Environment variable

You can also set CHRONARY_API_KEY in your shell environment. The CLI checks, in order, the --api-key flag, CHRONARY_API_KEY, then the config file profile.

Key security

• Keys are hashed with SHA-256 before storage; Chronary never stores the raw key
• Only the key prefix is shown after initial creation
• Regenerating an org key immediately revokes the previous org key
• Deleting an agent key immediately revokes that scoped key
• Never commit keys to source control; use environment variables

Error responses

| Status | Cause | Fix | |--------|-------|-----| | 401 Unauthorized | Missing or invalid API key | Check the Authorization: Bearer header | | 403 Forbidden | Agent key tried to access an org-only or out-of-scope resource | Use an org key or the matching agent key | | 429 Too Many Requests | Rate limit exceeded (10 req/sec) | Respect the Retry-After header | | 429 Too Many Requests | Monthly quota exhausted | Upgrade your plan or wait for monthly reset |

See Error Codes for the full error reference.