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.
Which key do I need?
Section titled “Which key do I need?”| You want to | Use |
|---|---|
| Script the API, run the CLI in CI, automate instances and backups | Organization API key (zb_) |
| Call the project endpoint from a browser or mobile app | Publishable project key (zbp_) |
| Call the project endpoint from a server, bypassing row-level security | Secret project key (zbs_) |
| Connect to a database with a driver | The instance’s credentials (Connect) |
Create an organization API key
Section titled “Create an organization API key”In the portal open API keys, or from the CLI:
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.
zb api POST /v1/orgs/{org}/service-accounts -d '{"name": "ci", "role": "developer"}'Rotate a key without downtime
Section titled “Rotate a key without downtime”Organization keys are rotated by overlap:
- Create the new key (
zb api-keys create), or for a service account mint an extra key withzb api POST /v1/orgs/{org}/service-accounts/<id>/keys. - Deploy the new key everywhere the old one is used.
- Check that the old key’s last used time stops moving (
zb api-keys list). - 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.
My key stopped working
Section titled “My key stopped working”| Symptom | Cause |
|---|---|
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_permission | The 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-limited | More 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.
I leaked a key
Section titled “I leaked a key”Act on the key first, then investigate.
- Revoke it now: API keys in the portal,
zb api-keys revoke <ID>, orzb 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. - Create a replacement and deploy it.
- 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. - If the key could reveal database credentials, rotate those credentials too (Rotating credentials).
- Remove the key from wherever it was published, including git history.
Removed members and their keys
Section titled “Removed members and their keys”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.
Still stuck?
Section titled “Still stuck?”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.