Developers · Authentication

Authentication.

Every request to the Alethia API carries a workspace API key as a bearer token. The key encodes which workspace it belongs to, what it can read or write, and, separately, any high-trust capabilities it carries.

Step one

Create a workspace API key

Keys are minted in-app by a workspace admin. There is no self-serve key creation from this site.

A workspace admin opens Settings → Integrations in the app (the ApiKeysSection, admin-only).
Create a key with a label, one or both scopes (read, write) and optional high-trust capabilities (restricted_records, manage_webhooks) — capabilities are never implied by scopes.
The plaintext key is shown exactly once at mint time and cannot be retrieved again; only its hash is stored.
Keys may carry an expiry (expiresAt) and can be revoked; revoked/expired keys authenticate as 401.
A key belongs to the workspace and stays valid until it is revoked or expires. It does not end when the admin who created it leaves the workspace or changes role.
(The underlying admin route is POST /api/workspace/{workspaceId}/api-keys — a member-session route, not part of the key-authenticated v1 surface.)

Step two

The Authorization header

Send the key as a bearer token on every request. There is no separate workspace parameter: the key resolves it.

Authorization: Bearer tk_{workspaceId}_{secret}

Authorization: Bearer tk_{workspaceId}_{secret} — the scheme is "tk", the workspaceId is embedded (not secret), and the secret is 64 hex characters (256 bits). Only a SHA-256 hash of the secret is stored server-side.

Scheme. The token is prefixed tk_ — a fixed marker, not part of the secret.
Workspace id. Embedded in the token itself. It is not secret; the secret half is what authenticates the request.
Secret. 64 hex characters (256 bits). Only a SHA-256 hash of the secret is stored server-side. The plaintext key shown once at mint time cannot be recovered afterwards.

Permissions

Scopes

Every key carries one or both scopes, chosen when it is minted.

read: Required for every GET. Also controls whether entity mutations echo the full record (write-only keys get { id, revision? } back).
write: Required for every POST/PATCH/DELETE.

Higher trust

Capabilities

Two capabilities carry higher-trust operations. Neither is implied by read or write: each is opted into explicitly when the key is minted.

restricted_records

Access records flagged restricted: true (entities, documents), the records that belong to or link a restricted entity (shareholdings, share classes, properties, deals), and permission to change restricted/viewerIds. Without it, those records are filtered from lists and indistinguishable from 404s, naming a restricted entity in a create or update is answered as if it did not exist, and list cursors are encrypted. The rule for a key without it is strict: a record is withheld when ANY entity it belongs to or names is restricted or does not exist.

manage_webhooks

Required for every /api/v1/webhooks operation (list, create, get, update, delete, test).

Plan

What your workspace needs

The public API is an Enterprise capability: the workspace subscription must be active on Enterprise (verifyApiKey returns 403 otherwise), and workspace/company access must not be suspended.

When something's wrong

Errors, in brief

Every error response is JSON with a human-readable message. See the full reference for every status code the API returns.

{
  "error": "Validation failed",
  "code": "invalid_request",
  "requestId": "req_8d41c7aa-52b9-4c53-8f0e-1b7e5d2a9c34",
  "fields": {
    "legalName": "Required"
  }
}

Every error is JSON with a human-readable error message, a stable machine code to branch on, and the requestId of the request. 422 validation failures add a fields map of field-path → message. Read the full errors & limits reference →

Continue reading

Reference

Make your first call.

The resources reference has a working curl example for every one of the API's endpoints.

View resources Book a 30-minute call