Authentication¶
Three credentials reach the API, and each has its own header. A credential sent in another one's header authenticates as nobody — an API key sent as a Bearer token, for example, is treated as a guest and refused by the collection rules.
| Credential | Header | Used by |
|---|---|---|
| API key | X-API-Key: <key> |
Scripts and integrations of the workspace's own |
| Session token | Authorization: Bearer <jwt> |
The app itself, after signing in with a passkey |
| Connection token | X-Revoked-Connection: <token> |
A connected tool, for the links it proposed |
Choosing a credential¶
Every key and every connected tool is described the same way: the
permissions it holds, from the catalogue at GET /api/permissions, and its
reach into the vault — none, the sections chosen for it, or, for an AI
assistant you run on your own machine, the whole vault. Ways to
connect compares them all.
| Situation | Credential | Reach |
|---|---|---|
| A personal setup — a cron job, a home server, a script keeping a record current | An API key, created in the app | Its permissions, and in the vault only the sections chosen for it |
| A tool used by other people with their own data | A connection, granted by each of them in their app | What it proposed or created, the permissions the owner gave it, and in the vault its own section and any the owner adds |
| Answers collected from other people into the own workspace | A request, optionally with a callback | What is submitted |
The difference lies in whose credential it is: an API key belongs to the workspace that created it, a connection to the person who granted it. An API key handed out for someone else's tool would be a long-lived string carrying all of its permissions, pasted into a foreign service. A connection, by contrast, is limited to the links that were approved, appears under Connected tools, lapses after 90 days and ends with a disconnect.
The in-app API preview on every create drawer shows a ready-to-run curl with
the correct header for the request in front of you.
First API call¶
For a script reading vault data, the prerequisites are an account, a section
containing an unencrypted record, and an API key created in
Settings → Developer → API keys. The key needs vault:read and access to
that section. A permission alone does not select any records.
SERVER='https://api.example.com'
read -r -s -p 'API key: ' REVOKED_API_KEY
printf '\n'
curl --fail-with-body "$SERVER/api/vault" \
-H "X-API-Key: $REVOKED_API_KEY"
The prompt reads the key without displaying it or putting the literal key in
shell history. The server address must be replaced with the actual installation.
A successful response contains a records array. For example, abbreviated to
the fields relevant here:
{
"records": [
{ "id": "RECORD_ID", "key": "shipping_address", "label": "Home", "type": "text" }
]
}
The list contains metadata, not values. A second call uses an id from that
response to read the value:
RECORD_ID='REPLACE_WITH_RETURNED_ID'
curl --fail-with-body "$SERVER/api/vault/$RECORD_ID" \
-H "X-API-Key: $REVOKED_API_KEY"
The response includes "value": "Musterstraße 12, Berlin" for a text record.
{"records":[]} means no records are currently readable with this key; it does
not mean authentication failed. A 403 vault_not_allowed means the key has no
vault read access. A 404 for a record can also mean it is outside the key's
selected sections. Full fields are in the vault reference.
Sign-in tokens have a different purpose. The session below authenticates a person to their own Revoked server. To let people sign in to a separate website, use Sign in with Revoked; that website creates its own session.
Signing in¶
People sign in with a passkey and nothing else; there is no password endpoint.
A passkey is bound to the server's address, so the ceremony runs on the
server's own page, GET /passkey, in the browser:
- The app makes a PKCE verifier, and opens
/passkey?mode=signin&challenge=<S256>&state=<random>. - The page calls
POST /api/passkeys/login/beginand…/finisharound the authenticator, and gets a one-time code. - The page opens
revoked://auth?code=…&state=…. - The app checks the state and redeems the code with its verifier at
POST /api/passkeys/token, which answers with the session token.
When the account has an authenticator app turned on, step 4 answers
401 two_factor_required with a challenge (good for five minutes) instead of
a session. The app asks for the current 6-digit code and sends
POST /api/passkeys/token/2fa {challenge, code}, which answers with the
session token. A challenge allows five codes. Where the server requires
two-factor authentication (REQUIRE_2FA, reported as twoFactor.required by
GET /api/server) and the account has none yet, the session carries
meta.twoFactorSetupRequired: true, and GET /api/2fa reports
setupRequired. Until it is set up, every other call with that session
answers 403 two_factor_setup_required, except /api/2fa/*,
/api/passkeys/*, /api/server, /api/features, the account's own record
and auth-refresh. The authenticator is managed with
POST /api/2fa/totp/setup, POST /api/2fa/totp/confirm {code} and
DELETE /api/2fa/totp {code}. A confirmation ends every session of the
account and answers with a fresh token for the device that confirmed. A code
is accepted once; a repeat inside its window is refused.
The code is useless to anything else that sees the link: it is bound to the
challenge, and spent on first presentation. Registration runs the same way
through /api/passkeys/register/* — with an email address where the operator
allows signups, or with a one-time ticket that adds a passkey to an existing
account. See Accounts.
Scripts do not sign in; they use an API key.
API keys¶
Create one in the app under Settings → Developer → API keys, or over the API by
creating an apiKeys record with a session token. The token is minted
server-side either way and returned exactly once — in the app as the
plaintext you copy, over the API in the X-Plain-Token response header. The
server stores only its hash; there is no way to retrieve it later.
A key can carry an expiresAt date, after which it stops authenticating as
if revoked.
A key carries the permissions granted when it was created, expanded to scopes. A request outside those scopes is refused with a named error rather than a generic 403, so the response says which grant is missing.
A key never opens the whole vault. It reaches only the sections chosen for it
when it was created: give it vault:read or vault:write together with
sections, the ids of your own sections in that workspace. It then reads and
writes through /api/vault, never through the
collection API:
curl -X POST "https://api.example.com/api/vault" \
-H "X-API-Key: $TOKEN" -H "Content-Type: application/json" \
-d '{"key":"now_playing","value":"Hunt: Showdown"}'
A record a key writes lands in the first of its sections (or the one named in
section), belongs to you, and is marked as written by the key. The key may
change only what it wrote; records you put in its sections are read-only to
it.
A vault permission without sections, or a raw record scope (record:*,
section:*), fails with api_key_vault_scope: a key is a string that ends up
pasted into other services, and one that reads the whole vault hands over
everything in it. Keys created before this rule keep what they were granted
until they expire or are revoked — the app marks them, and they should be
replaced.
curl "https://api.example.com/api/collections/links/records" \
-H "X-API-Key: $TOKEN"
The header value is in double quotes on purpose: '$TOKEN' in single quotes
is sent as the six literal characters, since the shell expands variables only
inside double quotes.
What a key reaches¶
A key acts as the member who created it, narrowed by its scopes. On every collection with a visibility (sections, records, shares, requests, templates, contacts, attestations), a key reads only rows its creator may read and changes only rows its creator may change. It never sees another member's private items, and loses access with its creator. Webhooks follow the same rule: an endpoint hears about an item only when the member who made it sees that item.
Connection tokens¶
A connection token is issued at POST /api/connect/token, in exchange for a
one-time code and its PKCE verifier, after the tool was connected in the app.
It travels as X-Revoked-Connection and opens only the /api/connection
and /api/vault endpoints; it is not a session, so no collection rule admits
it. The whole
flow, including a minimal working page, is described in
Building a tool.
Reading a failure¶
| Code | Meaning |
|---|---|
not_authenticated |
No usable credential arrived — wrong header, an unexpanded variable, or an empty value. |
invalid_api_key |
The header arrived, but no key matches it: mistyped, revoked, or expired. |
api_key_vault_scope |
The key being created asks for the vault without choosing sections, or for a raw record scope. |
vault_not_allowed |
The key was not given any part of the vault. |
vault_section_invalid |
A chosen section isn't one of yours in this workspace. |
connection_unauthorized |
No connection matches the X-Revoked-Connection token: mistyped, or the owner disconnected the tool. |
connection_expired |
The connection lapsed, 90 days after the owner last connected the tool. Only the owner can connect it again. |
connection_paused |
The owner paused the tool. The token works again once they activate it, so keep it. |
| A named scope error | The key is valid but was not granted that permission. Create a key with the right grants; scopes are fixed at creation. |
Revoking¶
Revoke from the same settings list. The next request with that key fails — there is no grace period.
Treat a key that has left its intended channel (pasted into a chat, committed, written to a log) as compromised: revoke it and create a replacement. The plaintext cannot be rotated in place, because the server never had it.