Authentication & errors

Updated 9 July 2026

Authentication & errors

Every endpoint in the API reference authenticates the same way and fails the same way. This page is the single source for both; the per-domain pages link here instead of repeating it.

Base path

All endpoint paths in the reference are relative to the /api prefix on your tenant's host:

http

POST https://<your-tenant-host>/api/v1/chat/completions

Authenticating requests

There are two credentials, for two situations:

API key (machine-to-machine). A service credential in the form ak.<key_id>.<secret>, passed in the X-API-Key header. This is the right choice for backend services. The plaintext secret is shown only once, at creation, and stored hashed; keys can be rotated and revoked — see Provisioning.
http
```
X-API-Key: ak.<key_id>.<secret>
```
Bearer token (user sessions). A short-lived JWT in the Authorization header, used when a human is signed in:
http
```
Authorization: Bearer <jwt>
```

Requests that operate inside a space also select it with the X-Aimable-Space-Id header. Your credential's principal must have access to that space — see the integration guide for the full walkthrough.

Errors

Gateway-level failures use a standard envelope:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { }
  }
}

Validation failures (422) use the field-level format instead, listing each offending input:

json

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "String should have at least 1 character",
      "type": "value_error",
      "input": ""
    }
  ]
}

Common statuses:

Status	Meaning
`400 Bad Request`	Invalid parameters; read `error.message`.
`401 Unauthorized`	Missing or invalid credential.
`403 Forbidden`	The principal lacks access to the space, a required permission or role, or the requested model is not allowed by the space's policy.
`404 Not Found`	The resource does not exist, or is outside your tenant.
`422 Unprocessable Entity`	Input failed validation; see `detail` for the offending fields.
`429 Too Many Requests`	Rate limit exceeded; retry after the `Retry-After` header.
`500 Internal Server Error`	Unexpected error; retry transient failures and quote `X-Request-Id` to support.

Build retry-with-backoff for 429 and 500.

Correlating requests

Every response carries X-Request-Id (quote it in support requests) and X-Routing-Details (JSON describing model resolution and applied governance). You can pass X-Trace-Id and X-Parent-Span-Id to correlate calls with your own tracing; the same identifiers surface as traces in the Console — see Observability.