Authentication and API keys

Every request carries one credential: an API key or a signed-in user's bearer token.

Which credential do I use?

You are building	Use	Because
A script, integration or agent that works in one workspace	Workspace key	It is locked to that workspace and acts with your role there
Set-up automation across organizations and workspaces (platform admins)	Platform key	It works in any workspace and on the `/platform-admin/` routes
A browser or app where a person is signed in	Bearer token	It acts as that person

Send it

X-API-Key: sk-…
X-Space-Slug: acme-analytics

A signed-in client sends Authorization: Bearer <oidc-token> instead of X-API-Key.
Every workspace route needs X-Space-Slug. Platform-admin routes and POST /api/v1/spaces/ do not.

Key types

Key	Acts as	Works in	Stops working when
Workspace key	Its owner, with the owner's role in that workspace	Its own workspace only	It is deleted or past its expiration date, its owner is disabled, or its owner loses access to the workspace
Platform key	The platform admin who created it	Any workspace, picked with `X-Space-Slug`, and the `/platform-admin/` routes	It is deleted or past its expiration date, its owner is disabled, or its owner stops being a platform admin

A key never has more rights than its owner: a Member's key cannot change roles.
Create workspace keys in Settings → Workspace → API Keys; platform admins create platform keys in Settings → Admin → API Keys.
Creating a workspace key needs the Create API keys permission (Editor and Admin by default) and a plan that includes API keys; otherwise the response is 403, or 402 with code FEATURE_NOT_AVAILABLE.
Keys are created, regenerated and deleted only in the web app. A key cannot manage keys.

Key format and storage

A key is sk- followed by 43 URL-safe characters. The web app shows its first 5 and last 4 characters afterwards.
The full key is shown once, when it is created or regenerated. Store it in an environment variable or a secrets manager; never commit or print it.
An optional expiration date can be set when the key is created or regenerated.
Regenerating issues a new value; the old value stops working immediately.
Keys carry scopes. The Alomana API needs the central-hub scope (labelled Agents in the web app). Keys created in the web app get central-hub, alo-files and aloflow by default.
Lab routes (/api/v1/diagnostics/) also need the lab scope (labelled Lab). It is not a default and works only together with Agents; see Lab.
Scopes are chosen when the key is created. To add one, create a new key.

What each key can call

Area	Workspace key (own workspace)	Platform key
Workspace: read, rename, settings, agent installs	✓ with a role that allows it	✓ any workspace
Delete a workspace	✓ creator only	✓ any workspace, with `DELETE /api/v1/platform-admin/spaces/{slug}/`
Members, invites, roles and permissions	✓ with a role that allows it	✓ any workspace
Agents: create, edit, delete, fork, import a bundle, export, run, follow and cancel runs	✓	✓
Apps: edit, open, secrets, copy, delete	✓	✓
Prompt templates, skills, skill sets and marketplace skills	✓	✓
Scheduled tasks, Slack installations, workspace context and templates	✓	✓
Connections and MCP connections: create, read, edit, delete, test, query, call	✓	✓
Files: upload, download links	✓	✓
Lab: environments, gym, diagnoses, certifications, and the agent chats the owner can open	✓ with the `lab` scope	✓ with the `lab` scope
Create a workspace (`POST /api/v1/spaces/`)	— `403`	✓
Users, all workspaces, organizations, platform settings (`/platform-admin/`)	— `403`; use a platform key	✓

The Auth column

Endpoint tables in these docs mark each route:

Auth	Accepts
Key or bearer	A workspace key in its own workspace, a platform key, or a bearer token
Platform key or bearer	A platform key or a bearer token; a workspace key gets `403`
Bearer only	A signed-in user's bearer token; an API key gets `401 {"detail": "Not authenticated"}`, or `403` on Alo Files

Only a signed-in user can: use chats (a key with the lab scope reads an agent's chats with GET /api/v1/diagnostics/agents/{id}/chats/ and .../chats/{chat_id}/); list or delete a chat's sandbox files; run a scheduled task now; start a new OAuth connection or install Slack; open a shared chat link; approve or reject a certification; manage workflows; use /organizations/current/; create their first workspace; accept an invite; change their profile or password; buy a plan or read billing details.

Check what a key can do

Method	URL	Returns	Auth
`GET`	`/api/v1/users/me/`	The key's owner: `id`, `email`, `first_name`, `last_name`, and `api_key_space_slug` for a workspace key	Key or bearer
`GET`	`/api/v1/authz/capabilities/me/`	`{"capabilities": [{"resource_type": "configurable_agent", "action": "create"}, …]}` for the key's workspace	Key or bearer
`GET`	`/api/v1/authz/permissions/me/?resource_type=&action=`	The same permissions with `id`, `name` and `description`, optionally filtered	Key or bearer

curl "$CENTRAL_HUB_URL/api/v1/authz/capabilities/me/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

A route needs the capability named after its resource and action, such as configurable_agent:create to create an agent; see Roles and permissions.

Troubleshooting

Response	Cause	Fix
`401` `{"detail": "Valid API key or Bearer token required"}`	The key is wrong, deleted, expired, lacks the `central-hub` scope, or its owner is disabled	Check the key in the web app; regenerate it if needed
`401` `{"detail": "Not authenticated"}`	An API key was sent to a Bearer only route	Use a signed-in user's token, or the key route the page names
`403` `{"detail": "API key is restricted to space '<slug>'"}`	A workspace key was sent without `X-Space-Slug`, with another workspace's slug, or to a route it cannot use	Send the key's own workspace slug; use a platform key for platform-admin routes
`400` `{"detail": "Missing X-Space-Slug header"}`	A signed-in request or a platform key called a workspace route without a workspace	Add `X-Space-Slug`
`403` `{"detail": "User does not have access to the selected space"}`	The key's owner is not a member of that workspace (for example, was removed)	Ask a workspace admin to add the owner back
`403` `{"detail": {"code": "API_KEY_SCOPE_MISSING", "scope": "lab"}}`	The key lacks the scope this route needs	Create a key with that scope; for Lab, tick Agents and Lab
`403` naming a missing permission	The owner's role lacks the permission the route needs	Ask a workspace admin to change the role; see Roles and permissions

On this page