API Keys
API Keys let external applications consume our API without using a person's credentials. Each key is bound to a tenant and has controlled permissions.
When to use an API Key
- Server-to-server integrations (webhooks, automated scripts, pipelines)
- Third-party applications that need programmatic access
- When you do not want to share a real user's credentials
Key types
| Type | Prefix | Header | Environment | Use |
|---|---|---|---|---|
| Secret | sk_ | X-API-Key | Server | Automation, backend integrations — authorization by privilege + operations, not by the key's role |
| Publishable | pk_ | X-Publishable-Key | Browser | Browser SDK — limited reads, billing checkout/portal, notifications (with a JWT) |
Secret keys must never be exposed in web or mobile applications.
The frontend API Keys dashboard lets you pick the key type (
secret/publishable) right when creating one, with a short explanation of each use in the form itself.
Security
Keys are stored as a SHA-256 hash. The full value is shown only at creation time and cannot be recovered afterwards.
Formats:
- Secret:
sk_{64 hex characters}— 67 characters in total - Publishable:
pk_{64 hex characters}— 67 characters in total
Permissions
Every key is super or normal (a privilege of that company, not of the platform). Normal keys declare a list of operations (area:verb, for example users:read); the list may be empty. Privilege and operations are not edited in place: only a rotation (which issues a new secret) can change them. Only an OWNER/ADMIN with a human session can create, keep, revoke or delete a super key. An API key cannot mint or alter supers.
Firewall on every request: if you authenticate with sk_ or pk_, access is decided by the privilege and the granted operations, not by the company role stored on the key.
| Privilege | What it can do |
|---|---|
| Super secret | Every operation in that company's catalogue |
| Super publishable | Only the pk_ ceiling already agreed (no invitations, no writes outside that ceiling) |
| Normal | Only the operations in its list; an empty list = authenticates and denies the whole catalogue |
A user's JWT session does not go through this firewall: it follows a person's permissions. A missing or revoked key → 401 with a generic message (Invalid API key / Invalid publishable key). An expired key → 401 with a different message (API key has expired), so the reason can be told apart. A valid key without the operation → 403 (Insufficient authorization for this operation).
UI click analytics (stats and project IDs) is granted with event-logger:read / event-logger:write on /event-logger/*. There is no analytics catalogue area and no routes under /analytics — see Event logger.
The key's role (owner / admin / member / viewer) is still stored and can be used by specific business rules (for example, who may assign OWNER), but it is no longer the mechanism that opens or closes the API for that key.
Additionally, you can specify scopes (legacy) and optionally a free-text description (max 500 characters) documenting the key's purpose.
Endpoints
Key management endpoints require authentication. Management requests may use a JWT or a secret key (X-API-Key: sk_…). Creating, listing, rotating, revoking or deleting with sk_ requires the api-keys:read or api-keys:write operation depending on the method. Minting or altering a super key still requires a human OWNER/ADMIN JWT. Requests to other modules with sk_/pk_ are authorized by the operations firewall, not by the key's role.
Creating an API Key
POST /api-keys
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"name": "My integration",
"keyType": "secret",
"privilege": "super",
"role": "member",
"scopes": ["users:read"],
"description": "Used by the billing integration", // optional, max 500 characters
"expiresAt": "2027-01-01T00:00:00Z" // optional
}For a publishable key (browser SDK), use "keyType": "publishable". The response will carry a pk_ prefix instead of sk_.
Response (201):
{
"id": "uuid",
"name": "My integration",
"keyPrefix": "sk_a1b2c3",
"key": "sk_abc123...",
"privilege": "super",
"operations": null,
"role": "member",
"scopes": ["users:read"],
"description": "Used by the billing integration",
"expiresAt": null,
"createdAt": "2026-01-01T10:00:00Z"
}The
keyfield appears only in this response. Store it somewhere safe.
privilege is mandatory (super or normal). If it is normal, operations must be sent (array, possibly empty). A publishable key cannot receive operations outside the pk_ ceiling (e.g. invitations:write). Requires the OWNER or ADMIN role; minting or keeping a super key requires a human session.
Plan gate: if the tenant has an active subscription whose plan does not declare the api_access catalogue feature (see Billing → Catalogue), creation is rejected with 403 Forbidden. A tenant with no active subscription at all is unaffected — it is the same billing-agnostic behaviour max_companies and max_users already apply (see Companies).
If the tenant has a resale plan assigned (see Owner plans), that plan governs instead: it grants access when it declares api_access in features, and blocks it when it does not (even if the tenant has no platform subscription at all). With no resale plan assigned, the platform plan gate described above applies unchanged.
Listing API Keys
GET /api-keys?page=1&limit=20
Authorization: Bearer <token>
X-Company-Id: <companyId>Returns the active tenant's keys. Includes privilege and operations. Never includes the key's full value.
Pagination — page (default 1) and limit (default 20, maximum 100) are optional. The response is a { data, total, page, limit } envelope, not a flat array. A page out of range is not an error: it returns data: [] with total reflecting the real count.
Reading an API Key
GET /api-keys/:id
Authorization: Bearer <token>
X-Company-Id: <companyId>Revoking an API Key
POST /api-keys/:id/revoke
Authorization: Bearer <token>
X-Company-Id: <companyId>Returns the updated key (200). The key becomes unusable immediately, but it is not deleted — it keeps appearing in the listing as revoked (traceability). Requires the OWNER or ADMIN role.
Deleting an API Key permanently
DELETE /api-keys/:id
Authorization: Bearer <token>
X-Company-Id: <companyId>Returns 204. Deletes the key from the database permanently and irreversibly — unlike revoking, it stops appearing in the listing. You can delete a key whether it is active or already revoked. Requires the OWNER or ADMIN role.
Rotating an API Key
POST /api-keys/:id/rotate
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"privilege": "normal",
"operations": ["users:read"]
}Revokes the current key and creates a new one (new secret). The body is optional: if you omit privilege or operations, the previous values are kept. Returns the full new key (just like creation). Rotating a super key (or converting one to super) can only be done by a human OWNER/ADMIN. If the key is already revoked → 409; no new key is issued.
Using a secret key in your requests
Send the key in the X-API-Key header:
GET /users
X-API-Key: sk_abc123def456...
X-Company-Id: <companyId>Using a publishable key (browser SDK)
Send the key in the X-Publishable-Key header:
GET /users
X-Publishable-Key: pk_abc123def456...
X-Company-Id: <companyId>Publishable keys are restricted to a subset of endpoints (reads on users/companies/settings, billing checkout/portal, etc.). Administration or write operations answer 403.
Notifications with a publishable key
Notification endpoints require double authentication: the publishable key (X-Publishable-Key) and an active user JWT (Authorization: Bearer).
GET /notifications
X-Publishable-Key: pk_abc123...
Authorization: Bearer <jwt>Lifecycle
Creation → Active
Rotation → Old key revoked + new key created
Revocation → Unusable immediately (the key is kept, marked as revoked)
Expiry → Rejected automatically once expiresAt < now
Deletion → Permanent removal from the database (an explicit, separate action)Revoked or expired keys are not removed from the database automatically (they keep the audit trail) — deleting them requires the explicit DELETE /api-keys/:id action.
Multi-tenancy
An API Key belongs to a single tenant. Using one tenant's key to reach another tenant's data is impossible.
Audit
Important operations emit domain events:
api-key.created— when a key is created (includesprivilegeandoperations)api-key.revoked— when a key is revokedapi-key.rotated— when a key is rotated (includes the resultingprivilegeandoperations)api-key.deleted— when a key is permanently deleted
Frequent use (every request) only updates the key's lastUsedAt field, without emitting an event per request.