API Authentication

How to authenticate API requests to AlonChat using API keys

API Authentication#

Programmatic access uses a credential AlonChat can verify. The same project operations are available through the API, SDK, CLI, and MCP; the credential type changes, not the business contract.

OAuth is not a second API key. It cannot call chat_with_agent, and an API key cannot approve its own held operation. See Connect with MCP.

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:

The create dialog also offers automation scopes such as knowledge.write and billing.read. Those scopes are the allowlist for project operations. A legacy flag does not grant every related scope: document and spreadsheet uploads need knowledge.write, and all four billing reads need billing_read. Enable only what that integration uses. Discovery, not the installed package, shows which operations the key can run.

Creating, listing, and revoking keys#

Create a key in Project Settings → API Keys. You can create up to 20 keys per project. The full secret is shown once. Restrict the key to selected agents when it does not need the whole project.

Revoke a key from the same page. Revocation takes effect immediately and cannot be undone.

Key management uses your signed-in AlonChat account. It is not available to the project API key itself. The older request that posted only a name and a permissions object is no longer accepted.

Using an API Key#

Include the API key in the Authorization header:

curl -X POST https://alonchat.com/api/v1/chat/{agentId} \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hello-001" \
  -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.

When a Call Is Refused#

Project operations return one receipt. A refusal looks like this:

{
  "operation": { "id": "billing.usage.get", "contractVersion": 1 },
  "requestId": "request-id",
  "correlationId": "correlation-id",
  "occurredAt": "2026-03-15T10:30:00Z",
  "status": "failed",
  "error": {
    "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"
    }
  }
}

The Chat API uses its own flat error object, such as { "error": "API key does not have chat permission" }, and does not use this receipt.

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:

The CLI prints the summary and URL to stderr. MCP sets isError: true and includes the receipt when the API returned one. 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#

• Connect to an Agent
• Build agents with Codex or Claude
• SDK and CLI
• MCP
• Connectors, subscriptions, and token costs
• Chat API
• Webhooks
• Billing & Plans