Mavera DocsAPI keys & admin
Key management and roles.
Who can administer
| Credential | Scope |
|---|---|
x-admin-token: <ADMIN_API_TOKEN> | Platform super-admin. Can target any workspace via a workspaceId in the body/query. |
| An API key whose member role is OWNER or ADMIN | Administers that key's own workspace. |
The admin-token compare is timing-safe. Set ADMIN_API_TOKEN to a long random secret in your environment.
Personal integration keys
On any connected docs page, use Generate integration key in the account bar. OWNER, ADMIN, and MEMBER roles can create or rotate their own key. The complete mav_ value is shown once and kept only in the current browser tab.
A personal integration key:
- stays scoped to the workspace where it was created
- rechecks the creator's current membership role on every API request
- stops working if that membership is removed or changed to VIEWER
- never gives a MEMBER owner-level authority
VIEWER accounts cannot mint keys or spend workspace credits.
Workspace and platform key administration
# Mint a workspace service key. The plaintext key is returned once.
POST /api/v1/keys -H "x-admin-token: $MAVERA_ADMIN_TOKEN" -d '{ "name": "Acme pilot" }'
# → data: { id, prefix:"mav_xxxx", key:"mav_…(48 hex)", note:"shown once" }
# List metadata. The secret is never returned.
GET /api/v1/keys -H "x-admin-token: $MAVERA_ADMIN_TOKEN"
# Revoke. The next call receives 401.
DELETE /api/v1/keys?id=<keyId> -H "x-admin-token: $MAVERA_ADMIN_TOKEN"Treat keys like passwords. Only the SHA-256 hash is stored — if a key leaks, revoke it and mint a new one. There's no way to recover the plaintext after creation.
What a key carries
- A
workspaceId— every call runs scoped to that workspace's data + credits. lastUsedAt— updated on each authenticated call, so you can find stale keys.revokedAt— set on revoke; the auth layer rejects revoked keys.
Members & roles
Workspace RBAC: OWNER > ADMIN > MEMBER > VIEWER. Manage via /api/v1/members (see Members & invitations). OWNER/ADMIN can mint keys and change billing.