> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt). # Authentication and API keys Authentication and API keys [#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? [#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 [#send-it] ```http X-API-Key: sk-… X-Space-Slug: acme-analytics ``` * A signed-in client sends `Authorization: Bearer ` 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-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**](https://platform.alomana.com/settings/workspace/api-keys); platform admins create platform keys in [**Settings → Admin → API Keys**](https://platform.alomana.com/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 [#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](../lab/overview). * Scopes are chosen when the key is created. To add one, create a new key. What each key can call [#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 [#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 [#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 | ```bash 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](../workspaces/roles-and-permissions). Troubleshooting [#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 ''"}` | 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](../workspaces/roles-and-permissions) |