Authentication and keys
Every request sends an API key in the Authorization header:
GET /api/v1/stories HTTP/1.1Host: dash.alethman.comAuthorization: Bearer alm_live_4Hc…A key belongs to one workspace and reads only what that workspace follows. There are no user tokens, no OAuth flow and no request signing: the key is the whole credential, so treat it like a password.
The key
Section titled “The key”A key is alm_live_ followed by 40 letters and digits. Alethman stores only a SHA-256 hash of it and its first 13 characters (so you can tell keys apart in the list), which is why it can be shown only once, when it is made. A lost key cannot be recovered; make a new one and revoke the old.
Making a key
Section titled “Making a key”Keys are made in the dashboard under Settings › API keys. Only a workspace owner or admin sees that page.
| Choice | What to pick |
|---|---|
| Name | What will use it (Risk desk ingest, Analyst notebook). Up to 80 characters. It labels the key in the list and in the audit log. |
| Scopes | Only what the program needs. The four read scopes are ticked by default; sources:write is not. |
| Expires | In 30 days, in 90 days (the default), in a year, or never. |
Limits that keep a stolen session from doing much:
- A workspace holds at most 20 active keys. Revoke one to make another.
- A workspace can make at most 30 keys an hour.
- Making and revoking a key are written to the workspace’s audit log with who did it.
Scopes
Section titled “Scopes”A scope is a permission a key carries. An endpoint answers 403 insufficient_scope to a key without its scope, and an MCP client sees only the tools the key’s scopes reach. GET /workspace needs no scope.
| Scope | Lets the key | Endpoints |
|---|---|---|
signals:read | Read articles in the workspace's scope. | GET /signals |
intel:read | Read stories, sector outlooks, forecasts and coordination findings. | GET /storiesGET /stories/{id}GET /outlooksGET /forecastsGET /coordination |
reports:read | Read the workspace's compiled reports, as JSON or Markdown. | GET /reportsGET /reports/{id} |
sources:read | Read the feeds the workspace follows and what they carried. | GET /sourcesGET /sources/items |
sources:write | Add and remove the workspace's own feeds. | POST /sourcesDELETE /sources/{id} |
Expiry, rotation and revocation
Section titled “Expiry, rotation and revocation”An expired or revoked key fails at once with 401 invalid_key. To rotate without downtime:
- Make the new key with the same scopes.
- Deploy it alongside the old one and switch over.
- Revoke the old key under Settings › API keys. The page lists when each key was last used, so you can confirm nothing still sends it.
A key also stops working when the person who made it stops being an active owner or admin of the workspace, or when the workspace is suspended. Make long-lived integration keys from a seat that will stay.
When a key is refused
Section titled “When a key is refused”| Status | Code | Why | What to do |
|---|---|---|---|
| 401 | unauthenticated |
No Authorization header, or not Bearer <key>. |
Send Authorization: Bearer alm_live_…. |
| 401 | invalid_key |
Unknown, revoked or expired key, a suspended workspace, or a maker who is no longer an owner or admin. | Check the key under Settings › API keys; make a new one. |
| 403 | insufficient_scope |
The key is valid but lacks the endpoint’s scope. The message names it. | Make a key with that scope. |
| 409 | workspace_not_ready |
The workspace has not finished its setup walkthrough. | An owner or admin finishes setup in the dashboard. |
| 429 | rate_limited |
30 failed key attempts in a minute from one address. | Wait 60 seconds (Retry-After: 60) and fix the key. |
A 401 carries a WWW-Authenticate header, as the HTTP standard asks. Neither 401 nor 403 carries rate-limit headers, because the request was never admitted.
{ "status": 401, "headers": { "content-type": "application/json", "cache-control": "no-store", "www-authenticate": "Bearer realm=\"alethman\"" }, "body": { "error": { "code": "unauthenticated", "message": "Send your key as: Authorization: Bearer alm_live_…" } }}{ "status": 403, "body": { "error": { "code": "insufficient_scope", "message": "This key does not carry the sources:write scope." } }}Keeping a key safe
Section titled “Keeping a key safe”- Keep keys in a secret manager or environment variables, never in source control.
- Never put a key in code that runs in a browser. The API does not serve cross-origin browser requests for this reason; call it from your server.
- One key per program, named for it, so revoking one breaks one thing.
- If a key may have leaked, revoke it first and investigate after.