API Overview & Authentication

Base URL

https://<your-worker>.workers.dev

All API routes are prefixed with /api/.

Request context headers

Every management API request must include headers that define the organizational context:

Header	Default	Description
`X-Alokai-CMS-Organization`	`"default"`	Organization ID
`X-Alokai-CMS-Space`	`"default"`	Space ID
`X-Alokai-CMS-Edition`	`"main"`	Edition ID (formerly `X-Alokai-CMS-Environment`)

If a header is omitted, Alokai CMS falls back to the defaults listed above.

Authentication

Session (UI)

The browser UI authenticates via a POST to /api/auth/login and receives an httpOnly session cookie (alokai-cms-session). All subsequent requests from the browser include this cookie automatically.

API key (programmatic)

Pass your API key in either header:

Authorization: Bearer <api-key>
X-API-Key: <api-key>

API keys are space-scoped. You do not need to pass X-Alokai-CMS-Space separately — the key implies the space.

Full example

curl https://your-worker.workers.dev/api/entries \
  -H "Authorization: Bearer default_sk_abc123..." \
  -H "X-Alokai-CMS-Organization: default" \
  -H "X-Alokai-CMS-Edition: main"

Response format

All API responses return JSON. Errors follow this shape:

{
  "error": "Not found",
  "status": 404
}

Impersonation (super_admin only)

Super admins can impersonate any user by adding:

X-Alokai-CMS-Impersonate: <user-id>

The request is processed as if that user made it.

Rate limiting

There is no built-in rate limiter. For production deployments, use Cloudflare Rate Limiting at the CDN layer.

Known API / terminology inconsistencies

The environment → edition and store → market rename is complete in the database, routes, and client, but a few contract-level identifiers were left on the old names. These are flagged here for the engineering team to decide whether to finish the rename; clients should treat the names below as the current contract.

Inconsistency	Where	Note
`/markets` returns a `{ "stores": [...] }` body	`apps/cms/src/server/routes/markets.ts` (response schema + handler)	The route path is `markets`, but the JSON envelope key is still `stores`. Clients read `d.stores`.
`api_keys.stores` allow-list column	migration `047`	Deliberately left named `stores`; holds market IDs.
MCP stdio env var `ALOKAI_CMS_ENVIRONMENT_ID`	`packages/cms-mcp` (`api-client.ts`, `bin/index.mjs`)	The stdio transport still reads `ALOKAI_CMS_ENVIRONMENT_ID`, while the HTTP transport uses the `X-Alokai-CMS-Edition-Id` header.
`cms-cli` built binary flag	`packages/cms-cli/bin/index.mjs`	The compiled `bin` still reads `--environment-id`; the `src/` source uses `--edition-id`. The binary needs a rebuild to match the documented flag.