Skip to content

Authentication and keys

Every request sends an API key in the Authorization header:

GET /api/v1/stories HTTP/1.1
Host: dash.alethman.com
Authorization: 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.

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.

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.

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.

ScopeLets the keyEndpoints
signals:readRead articles in the workspace's scope.GET /signals
intel:readRead stories, sector outlooks, forecasts and coordination findings.GET /stories
GET /stories/{id}
GET /outlooks
GET /forecasts
GET /coordination
reports:readRead the workspace's compiled reports, as JSON or Markdown.GET /reports
GET /reports/{id}
sources:readRead the feeds the workspace follows and what they carried.GET /sources
GET /sources/items
sources:writeAdd and remove the workspace's own feeds.POST /sources
DELETE /sources/{id}

An expired or revoked key fails at once with 401 invalid_key. To rotate without downtime:

  1. Make the new key with the same scopes.
  2. Deploy it alongside the old one and switch over.
  3. 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.

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.

A request with no key
{
"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_…"
}
}
}
A read-only key trying to add a source
{
"status": 403,
"body": {
"error": {
"code": "insufficient_scope",
"message": "This key does not carry the sources:write scope."
}
}
}
  • 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.