API keys and management tokens
NamiDB Cloud has two kinds of credentials. Each works only with its own API.
| API key | Management token | |
|---|---|---|
| Looks like | nmdb_live_… | nmdb_mgmt_… |
| Used for | Running Cypher: HTTP, Bolt, MCP | Managing the organization: the management API, CLI, Terraform |
| Endpoint | https://db.namidb.com | https://app.namidb.com/api/v1 |
| Permissions | A role (read-write or read-only) and a set of databases | A scope (read, write or admin) |
| Created by | Owners, admins and developers (console, API, CLI, Terraform) | Owners and admins, in the console, with two-factor authentication |
| Per organization | 50 active | 25 active |
| SDK class | NamiDB | ManagementClient |
Both are shown once, when they are created. NamiDB stores only a keyed hash, so nobody (including NamiDB) can show them to you again. Lost one? Revoke it and create another.
Keep them in a secret manager or server-side environment variables, never in source control, and never ship a read-write key in browser or mobile code.
API keys
Create them under API keys → Create key, with POST /api-keys,
namidb keys create or the namidb_api_key Terraform resource. A key has:
- A role. Read & write runs any statement. Read only runs queries
only: writes are refused by the engine itself (
403 read_only_key), on HTTP, Bolt and MCP alike. - Databases. All databases (including ones created later), or a list.
A request for any other database is refused (
403 database_not_in_scope). - An expiry. Never, 7 days, 30 days, 90 days (the default) or 1 year; with the API, any time within 2 years. You are emailed 7 days and 1 day before a key expires.
- An optional IP allowlist of its own. See IP allowlists.
The console lists each key with its prefix, last four characters, role, databases, expiry, and when it was last used.
Rotating a key
Rotate issues a new key with the same name, role, databases and IP
allowlist, and keeps the old one working for an overlap you choose: 1, 7
(default) or 30 days. Deploy the new key during the overlap; the old key
stops by itself at the end. With the API: POST /api-keys/{id}/rotate
(overlap_days); the response holds the new token and
previous_key.expires_at.
Revoking a key
Revocation takes effect across the data API within about two seconds, including open Bolt sessions. Revoked and expired keys stay listed (with their status) for the record.
Key lifetime policy
Owners and admins can cap how long new keys may live: 7, 30, 90, 180 or 365
days (API keys → Lifetime policy). New keys and rotations must then expire
within it (422 lifetime_policy otherwise); management tokens follow the
same policy. Existing keys are not changed.
When the creator leaves
API keys belong to the organization, not to a person: they keep working when the member who created them leaves or deletes their account. Review keys when people leave, and rotate the ones they could have copied.
Management tokens
Create them under Settings → Management API (owners and admins, with
two-factor authentication on your account). An admin token can also issue
tokens for other tools through the
management API,
namidb tokens create in the CLI
or the Terraform
resource namidb_management_token, for example a short-lived write token
for a CI job.
| Scope | Allows |
|---|---|
read | Every GET except invitations and management tokens: the organization, databases, backups, restores, clones, exports and their files, API key metadata, IP allowlists, usage, members, support tickets |
write | read, plus creating and deleting databases, backups, restores, clones and exports, and opening and answering support tickets |
admin | write, plus creating, rotating and revoking API keys, IP allowlist entries, removing members, and managing invitations and management tokens |
- Never more than its creator. A token works only while its creator is
still an owner or admin of the organization (and, when the organization
requires it, still uses two-factor authentication or SSO). Otherwise it
answers
403 token_inactive. Tokens never grant or remove the owner role. - Tokens made by tokens. A token created through the API, CLI or Terraform acts for the same person as the token that created it, is never broader in scope and never outlives it. It works only while that token does: revoking the creating token revokes everything it created, and when it expires or becomes inactive, so do the tokens it created. The console shows which token created each one.
- Expiry: 30 days, 90 days, a year, or never, within the organization’s key lifetime policy.
- Visibility: the console shows each token’s scope, creator, expiry, and when and from which address it was last used.
- Audit: changes made with a token appear in the audit log as Token “name”.
- Revocation takes effect on the token’s next request.
Other credentials
- SCIM tokens (
nmdb_scim_…) let your identity provider provision members. They are created on the Single sign-on page and work only on the SCIM endpoint. See SSO and SCIM. - Webhook signing secrets (
whsec_…) sign the events NamiDB sends you. See Alerts and webhooks.