API Authentication

How to authenticate API requests to AlonChat using API keys

API Authentication#

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

API Keys#

API keys are managed at the project level. Create them in Project Settings → API Keys, and optionally restrict a key to a single agent. (Older agent-scoped keys still work where they exist.)

Keys use the sk- prefix (for example sk-a1b2c3…) and are shown in full only once at creation.

Permissions#

API keys have configurable permissions. Common ones:

PermissionDescription
chatSend messages and receive agent responses
read_sourcesRead knowledge sources for the scoped agents
read_agentsRead agent metadata for the project
read_conversationsRead bounded production transcripts for the scoped agents
agent_design_readInspect setup, validate proposals, and read design sessions
agent_design_writeSave review-gated agent-design drafts; does not publish them
billing_readRead project usage, credit, and invoice information

Only enable the permissions each integration needs.

Creating an API Key#

Endpoint: POST /api/projects/{projectId}/api-keys

Request#

json
{
  "name": "Production Key",
  "permissions": {
    "chat": true,
    "read_sources": false,
    "read_agents": false,
    "read_conversations": false,
    "agent_design_read": false,
    "agent_design_write": false,
    "billing_read": false
  }
}

Response#

json
{
  "data": {
    "id": "key-uuid",
    "key_prefix": "sk-xxxx",
    "name": "Production Key",
    "permissions": {
      "chat": true,
      "read_sources": false,
      "read_agents": false,
      "read_conversations": false,
      "agent_design_read": false,
      "agent_design_write": false,
      "billing_read": false
    },
    "key": "sk-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/projects/{projectId}/api-keys

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

json
{
  "data": [
    {
      "id": "key-uuid",
      "key_prefix": "sk-xxxx",
      "name": "Production Key",
      "permissions": {
        "chat": true,
        "read_sources": false,
        "read_agents": false,
        "read_conversations": false,
        "agent_design_read": false,
        "agent_design_write": false,
        "billing_read": 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:

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

Rate Limits#

The Chat API is rate-limited to 60 requests per minute per API key. Rate-limit headers are returned on responses. Exceeding the limit returns 429 with retry guidance.

Revoking an API Key#

Endpoint: DELETE /api/projects/{projectId}/api-keys/{keyId}

Revoked keys are immediately invalidated and cannot be restored.

When a Call Is Refused#

Every refusal an integration could act on carries a resolution alongside the error code:

json
{
  "code": "SCOPE_DENIED",
  "message": "The actor does not have the required operation scope",
  "retryable": false,
  "details": { "missingScopes": ["billing.read"] },
  "resolution": {
    "actor": "key_owner",
    "summary": "This API key does not carry billing.read. Ask a project owner to enable the matching permission on the key in Project settings → API.",
    "url": "https://alonchat.com/dashboard"
  }
}

retryable answers the transport: should the same request be sent again. resolution answers the actor: who can lift the refusal and where. Most denials are retryable: false and still resolvable, so an agent should read resolution before deciding a call is permanently blocked.

actor is one of:

ValueMeaning
callerChange the request and try again — no human needed
key_ownerWhoever issued the API key or approved the MCP connection must act
project_ownerA project owner or admin must act in the AlonChat dashboard

The CLI prints the summary and URL to stderr. The MCP server appends them to the tool result, so a connected model can relay the exact next step instead of guessing. An error with no resolution has no known route out — treat it as a genuine failure and report it.

Security Best Practices#

  1. Never commit API keys to version control
  2. Use environment variables or a secrets manager in production
  3. Restrict keys to one agent when an integration only needs one bot
  4. Rotate keys if they may have been exposed
  5. Use server-side code only — never embed keys in browsers or mobile apps

Related Pages#