Project keys and JWKS

Applications authenticate to the project endpoint with project keys. They are separate from the organisation API keys (zb_...) that manage your account through the REST API and the CLI.

Publishable and secret keys

Kind	Prefix	Role	Use it in
Publishable	zbp_	anon	Browsers, mobile apps, anything a user can inspect
Secret	zbs_	service_role	Servers, jobs and CI only; it bypasses row-level security

Send the key as the apikey header, and as Authorization: Bearer <key> when there is no user session. That is exactly what supabase-js and the other Supabase clients send.

shell

zb projects keys create --name web --kind publishable     # printed once; store it now
zb projects keys create --name worker --kind secret       # servers only
zb projects keys list                                     # prefixes, roles and last use; never the key
zb projects keys revoke pak_01jb...                       # refused within seconds

A publishable key can never reach SQL over HTTPS (/query/v1) or any secret-only route. Keys may carry an expiry (--expires, RFC 3339). Creating and revoking keys is audited and recorded as a security event.

Signing keys and JWKS

Each project signs its users’ session tokens with its own ES256 key. The private key is generated inside the region that runs the project and never leaves it; the control plane holds only the public half.

JWKS URL

https://<ref>.us-east.databasezy.com:8443/auth/v1/.well-known/jwks.json

Use the JWKS to verify a user’s token in your own backend, for example with jose:

verify.ts

import { createRemoteJWKSet, jwtVerify } from "jose";

const jwks = createRemoteJWKSet(
  new URL("https://<ref>.us-east.databasezy.com:8443/auth/v1/.well-known/jwks.json"),
);
const { payload } = await jwtVerify(token, jwks); // payload.sub is the user id, payload.role "authenticated"

Rotate the signing key

shell

zb projects jwt-keys list      # kid, status (current, previous, pending) and the JWKS URL
zb projects jwt-keys rotate    # new key is pending until the region generates it, then current

After a rotation the previous key keeps verifying until the next rotation, so sessions issued before it stay valid. Rotating twice in a row retires the oldest key and signs everyone out who still holds a token from it.

Limits

Platform limits on each plan

Limit	Free	Solo	Team	Enterprise
Active API keys per project	5	20	50	Unlimited
Requests per second per key	20	100	500	2,000

Requests above a key’s rate are refused with 429 Too Many Requests; retry with backoff.