API Authentication

How to authenticate API requests to AlonChat

API Authentication#

AlonChat uses API keys to authenticate programmatic access to your agents.

API Keys#

Each agent can have up to 5 API keys. Keys are scoped to a specific agent and cannot access other agents.

Permissions#

API keys have configurable permissions:

Creating an API Key#

Endpoint: POST /api/agents/{agentId}/api-keys

Request#

{
  "name": "Production Key",
  "permissions": {
    "chat": true,
    "read_sources": false
  }
}

Response#

{
  "data": {
    "id": "key-uuid",
    "key_prefix": "ak_xxxx",
    "name": "Production Key",
    "permissions": { "chat": true, "read_sources": false },
    "key": "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "message": "API key created. Save this key - it will not be shown again!"
}

Important: The full key is only returned once on creation. Store it securely.

Listing API Keys#

Endpoint: GET /api/agents/{agentId}/api-keys

Returns keys with metadata (prefix only, not full key):

{
  "data": [
    {
      "id": "key-uuid",
      "key_prefix": "ak_xxxx",
      "name": "Production Key",
      "permissions": { "chat": true, "read_sources": false },
      "is_active": true,
      "last_used_at": "2024-01-01T12:00:00Z",
      "total_requests": 1523,
      "created_at": "2024-01-01T00:00:00Z",
      "expires_at": null
    }
  ]
}

Using an API Key#

Include the API key in the Authorization header:

curl -X POST https://alonchat.com/api/agents/{agentId}/chat \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

Revoking an API Key#

Endpoint: DELETE /api/agents/{agentId}/api-keys/{keyId}

Revoked keys are immediately invalidated and cannot be restored.

Security Best Practices#

1. Never commit API keys to version control
2. Use environment variables to store keys
3. Rotate keys regularly for production systems
4. Use minimal permissions (only grant read_sources if needed)
5. Monitor usage via the last_used_at and total_requests fields

Key Format#

API keys follow this format:

• Prefix: ak_ (4 characters)
• Random string: 32 cryptographically secure characters

Example: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate Limits#

API requests are rate-limited per key:

• Chat endpoints: 60 requests/minute
• Read endpoints: 100 requests/minute

Exceeding limits returns 429 Too Many Requests.

Errors#