Skip to main content
Every REST API request except /healthz needs a workspace-scoped API key, sent as a bearer token.
Shell
It is the same key and the same header as the MCP server. One key reaches both surfaces; you do not need a second credential to add the other. The REST API takes a key and nothing else. OAuth access tokens belong to the MCP server, where a client can open a browser; an API called by a script should not need a consent screen, and a key is the one credential that works where nothing can open a browser at all.

​
The key

Mint a key under Settings → Your assistant at app.attensira.com/settings/access. See API keys for minting, scopes and revocation. The format is atn_live_ followed by 32 hexadecimal characters:
Key format
The key is displayed exactly once, because only a hash is stored. Attensira cannot re-display it — a lost key is replaced, not recovered.
REST keys do not expire. A key stays valid until you or a workspace admin revokes it, so a script you deploy once keeps running without anyone re-authorizing it. There is no rotation deadline and no maximum age.
Access tokens obtained through OAuth do expire, and the client refreshes them for you. That lifetime is a property of the token, not of this API — nothing about /v1 times out a key.

​
The credential names the organisation

A credential belongs to your organisation and names one workspace inside it as the default. Every /v1 endpoint takes an optional ?project=<workspace id>; omit it and the default is used. No workspace id appears in a path segment or a body field — the query parameter is the only place one can be named, and it is checked against the organisation the credential belongs to. A workspace outside it comes back 404, indistinguishable from one that does not exist, so naming an id you do not own tells you nothing. One credential therefore covers every workspace in the organisation. GET /v1/account returns them in workspaces, alongside the resolved one in project.

​
What a 401 means

A request with a missing, malformed or unusable key gets:
401 response
The response carries the challenge, so a client knows which scheme to retry with:
A 401 covers four different situations deliberately, and neither the message nor the challenge distinguishes them: the header was absent or the wrong shape, the credential does not exist, it was revoked, or it expired. The challenge is one constant string for all of them — a caller who could tell them apart could probe for which credentials exist. Check the key at app.attensira.com/settings/access rather than inferring from the response.
A key that is real but was minted read-only gets 403, not 401, from an endpoint that writes: the error envelope carries type: "forbidden" and the header WWW-Authenticate: Bearer error="insufficient_scope", scope="write". The distinction matters: a 401 is a reason to check the key, a 403 is not, and a client that reacts to one as if it were the other throws away a working key and fails identically. Keys cannot be widened after minting — mint a read-and-write key. GET /v1/account returns the credential’s scopes, so that is where to look when a write fails and a read succeeds.

​
How the token travels

The API service checks only the shape of the key at the door — the atn_live_ prefix and 32 hex characters — and rejects anything else before it can become a round trip, so a typo never reaches the backend or its logs. That check is not authentication. The token itself is forwarded verbatim to the Attensira backend, which owns the real validation: hash lookup, revocation, expiry, scopes and per-key rate limiting. Two consequences worth knowing:
  • Redirects are never followed. A 3xx is treated as the response rather than chased, because following one could re-send a live key to another host.
  • A key is never cached or mirrored. Revoking a key at the dashboard takes effect on the next request; there is no copy of it in the API layer to go stale.

​
Keeping a key safe

Send it from a server, never from a browser or a mobile app — anything shipped to a client device is public, and this key can delete prompts and spend credits. Store it in your platform’s secret store and read it from an environment variable. A key in a committed .env, a CI log or a screenshot should be revoked and replaced rather than reasoned about. Mint one key per integration. Keys carry last_used_at, so a per-integration key is the difference between revoking one job and breaking every job you have.