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.

  1. A workspace admin opens Settings → Integrations in the app (the ApiKeysSection, admin-only).
  2. 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.
  3. The plaintext key is shown exactly once at mint time and cannot be retrieved again; only its hash is stored.
  4. Keys may carry an expiry (expiresAt) and can be revoked; revoked/expired keys authenticate as 401.
  5. (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 unlock 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) and permission to change restricted/viewerIds. Without it, restricted records are filtered from lists and indistinguishable from 404s; list cursors are encrypted.
manage_webhooks
Required for every /api/v1/webhooks operation (list, create, get, update, delete, test).

Plan & modules

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.

ResourceModule required
Entitiestithe
Peopletithe
Dealssocage
Documents— (scope + plan only)
Propertiestithe
Fund commitmentstithe
Cap table — Share classestithe
Cap table — Shareholdingstithe
Webhook subscriptions— (scope + plan only)

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",
  "fields": {
    "legalName": "Required"
  }
}

Every error is JSON with a human-readable error message. 422 validation failures add a fields map of field-path → message. Read the full errors & limits reference →

Next

Continue reading

Reference

Resources

Every resource and endpoint, with parameters, field tables and a curl example each.

Read more →

Events

Webhooks

Subscribe with the manage_webhooks capability, verify the HMAC signature, and retry policy.

Read more →

Contract

Errors & limits

The full error envelope, every status code, rate limits and pagination.

Read more →

Ready to make your first call?

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

View resourcesRequest demo