Skip to content

API keys and management tokens

NamiDB Cloud has two kinds of credentials. Each works only with its own API.

API keyManagement token
Looks likenmdb_live_…nmdb_mgmt_…
Used forRunning Cypher: HTTP, Bolt, MCPManaging the organization: the management API, CLI, Terraform
Endpointhttps://db.namidb.comhttps://app.namidb.com/api/v1
PermissionsA role (read-write or read-only) and a set of databasesA scope (read, write or admin)
Created byOwners, admins and developers (console, API, CLI, Terraform)Owners and admins, in the console, with two-factor authentication
Per organization50 active25 active
SDK classNamiDBManagementClient

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.

ScopeAllows
readEvery 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
writeread, plus creating and deleting databases, backups, restores, clones and exports, and opening and answering support tickets
adminwrite, 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.