Skip to content

Help

API keys: org keys vs project keys, rotation and leaked keys

Tested with:Databasezy API v1 · zb CLI 0.1

Databasezy has two kinds of keys. Organization API keys (they start with zb_) manage your account through the REST API and the zb CLI. Project keys (zbp_ publishable, zbs_ secret) let your application call a project’s platform endpoint (auth, Data API, storage, functions). Neither kind is a database password: database credentials are separate and are rotated per instance. Every key’s secret is shown once, when it is created.

You want toUse
Script the API, run the CLI in CI, automate instances and backupsOrganization API key (zb_)
Call the project endpoint from a browser or mobile appPublishable project key (zbp_)
Call the project endpoint from a server, bypassing row-level securitySecret project key (zbs_)
Connect to a database with a driverThe instance’s credentials (Connect)

In the portal open API keys, or from the CLI:

shell
zb api-keys create --name ci-deploy --role developer --scope instances:read,backups:write --expires 2027-01-01T00:00:00Z
  • The key acts with its role narrowed by its scopes, and it can never do more than you can.
  • You need apikeys:manage (owners and admins), and a second factor from the last 15 minutes when you create it in the portal. Without two-factor authentication, creating a key is refused (two-factor authentication).
  • Store the printed secret in your secret manager at once. It cannot be shown again; keys are stored hashed.

For automation that should not depend on a person, use a service account: its keys keep working when people join or leave.

shell
zb api POST /v1/orgs/{org}/service-accounts -d '{"name": "ci", "role": "developer"}'

Organization keys are rotated by overlap:

  1. Create the new key (zb api-keys create), or for a service account mint an extra key with zb api POST /v1/orgs/{org}/service-accounts/<id>/keys.
  2. Deploy the new key everywhere the old one is used.
  3. Check that the old key’s last used time stops moving (zb api-keys list).
  4. Revoke the old key: zb api-keys revoke <ID>. Revocation is immediate.

Project keys rotate the same way: zb projects keys create, deploy, then zb projects keys revoke <ID>. Details and the project signing keys are on Project keys and JWKS.

SymptomCause
401 “invalid api key”The key is mistyped or truncated, or is not an organization key (project keys do not work against the REST API)
401 “api key revoked” or “api key expired”Create a new key. zb api-keys list shows active keys and their expiry
401 “api key suspended pending a security review”Our automatic security response suspended it, for example after it was found in a public place. You received an email
403 forbidden with required_permissionThe key’s role or scopes do not include that permission. Create a key with the right scopes
403 “needs a person signed in to the portal”Some actions refuse API keys: changing or cancelling the plan, acting as one of your app’s end users
429 rate-limitedMore than 600 requests a minute for this key (burst 100). Honour Retry-After

An org admin can reinstate a suspended key with zb api POST /v1/orgs/{org}/api-keys/<ID>/actions/unsuspend, but only do that if you are sure the key did not leak. Otherwise revoke it and create a new one.

Act on the key first, then investigate.

  1. Revoke it now: API keys in the portal, zb api-keys revoke <ID>, or zb projects keys revoke <ID> for a project key. For a service account, revoke the key, or disable the account to revoke all of its keys.
  2. Create a replacement and deploy it.
  3. Check the audit log (Audit log in the portal) for actions taken with the key since it leaked. A leaked secret project key (zbs_) bypasses row-level security, so also review the data it could reach.
  4. If the key could reveal database credentials, rotate those credentials too (Rotating credentials).
  5. Remove the key from wherever it was published, including git history.

Removing a member does not revoke API keys they created. After someone leaves, review API keys and revoke theirs, and move automation to a service account.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket, category security for a leak, otherwise account) and include the key id or its prefix (never the full key), the exact error, the x-request-id response header and the time in UTC. Never paste full keys, passwords, connection strings with passwords or patient data (PHI) into a ticket. See How to get help.