Keys and security

Every client needs two things: your project’s API address and an API key. This page explains what each key can do, how scopes narrow it, how requests are authenticated, and what to check before you go live. To create and manage keys in Studio, see API keys.

The two kinds of key

	Publishable key	Secret key
Starts with	`pb_pk_`	`pb_sk_`
Where it lives	Browsers, mobile apps, anywhere	A server you control
What it does	Identifies your project. Every request is limited by your access rules and the signed-in person	Bypasses every access rule and can manage users, settings and the project’s definitions
In a rule	`is_service` is false; rules apply in full	`is_service` is true; rules always pass
Safe to publish	Yes	Never
Can hold management scopes	No	Yes

How a request is authenticated

Every call carries a key in the apikey header. Calls made on behalf of a signed-in person also carry their access token:

GET /rest/v1/tasks HTTP/1.1
apikey: pb_pk_…
Authorization: Bearer eyJhbGciOi…

The gateway reads the key. A missing key is missing_api_key and a bad one invalid_api_key (both 401).
It checks the key’s limits: expiry, allowed browser origins, allowed addresses, allowed routes, rate limit, and your plan’s quotas.
It checks the key’s scopes (below).
If there is a bearer token, it identifies the person: their id, roles, organization and assurance level.
The access rule for what’s being asked is evaluated with all of that.

The SDKs do all of this for you: give them the key and they add the headers, refresh tokens and retry politely.

Scopes

A scope names something a key may do. A scope has the form family:read, family:write or family:*:

read allows looking: GET, HEAD and OPTIONS requests.
write allows changing: every other method.
* allows both.
A lone * is everything.

A key with no scopes may do anything its role allows. A key with scopes may make only the requests its scopes name, whichever route they reach. The check happens at the edge for every request, so no route can forget it.

The scope families

Family	Covers	Secret key only
`data`	Reading and writing your tables through the data API
`storage`	Files in buckets
`auth`	Sign-in and account calls
`flows`	Calling flows
`ai`	Calling AI models and running agents
`realtime`	Channels and publishing
`users`	Managing people	yes
`roles`	Roles and permissions	yes
`resources`	Tables, policies and routes (definitions)	yes
`database`	The SQL console and database tools	yes
`buckets`	Bucket definitions	yes
`backups`	Backups and restores	yes
`agents`	Agent definitions, knowledge bases and connections	yes
`aimodels`	AI providers and models	yes
`webhooks`	Webhook definitions	yes
`events`	Events and jobs	yes
`flowdefs`	Flow definitions	yes
`mail`	Mail delivery and activity	yes
`templates`	Mail templates	yes
`channels`	Realtime channel rules	yes
`keys`	API keys	yes
`secrets`	Secrets and settings	yes
`firewall`	Custom domains	yes
`monitoring`	Activity and monitoring	yes
`admin`	Everything, including project-wide actions	yes

A publishable key can only hold the application families (data, storage, auth, flows, ai, realtime). Management scopes need a secret key because the management API is out of a browser’s reach.

Presets

When you create a key, Start from a preset and adjust:

Preset	Scopes
Full access	none (no restriction)
Read-only app	`data:read`, `storage:read`
App backend	`data:`, `storage:`, `auth:`, `flows:`, `realtime:*`
Resources only	`data:`, `resources:`
User directory (read)	`users:read`
User manager	`users:*`
Webhook manager	`webhooks:*`
Monitoring (read)	`monitoring:read`
Deploy and configure	`resources:`, `roles:`, `flowdefs:`, `templates:`, `secrets:`, `buckets:`, `webhooks:`, `events:`
AI assistant (read-only)	Read access to definitions, data, flows, events, buckets, templates, mail, webhooks, models and agents
AI builder	Build access to tables, flows, events, buckets, templates and webhooks; read the rest
Administrator	`admin:*`

The two AI presets are what AI tools use.

Other limits on a key

Besides scopes: an expiry, allowed IP ranges and allowed routes (GET /rest/v1/*). The environment also has a list of websites allowed to use publishable keys. All refuse the call at the gateway. See API keys.

Rules of thumb

Put the publishable key in client code. It is meant to be seen.
Keep the secret key in an environment variable on a server. The browser build of the client refuses to start with one.
Never trust the browser for permissions. Your access rules run on the server for every request, whatever the client sends.
Do not store anything sensitive in user_metadata, since the user can edit it. Store permissions in roles or app_metadata, set from a server.
Give each app and job its own key with the fewest scopes it needs.

Choosing a key on a server

You are doing	Use
Admin work, jobs, imports, scripts	A secret key, scoped to what the job needs
Handling a request for one signed-in user	The publishable key with that user’s access token, so rules apply to them
A service calling your API as itself	A machine identity
An AI tool	A scoped key from AI tools

See Node.js for both patterns.

Rotating and revoking

If a secret key may have leaked, rotate it: create the replacement, deploy it, and let the old one expire after a grace period. If you are sure it leaked, revoke it now. See API keys.

Redirect addresses

Links in emails (confirmation, reset, invite) and social sign-in can only return to addresses you have listed under Users & auth → Domains. List exactly your app’s addresses, including http://localhost:… for development, and no wildcards you do not need. See Redirect URLs.

Go-live security checklist

Common mistakes

Mistake	Why it hurts	Fix
A secret key in a browser or app bundle	Anyone can read your data and change your project	Revoke it now; use the publishable key in clients
Trusting `user_metadata` for permissions	The person can edit it	Use `roles` or `app_metadata`
One key for everything	Revoking it breaks every app	One key per app, scoped
Rules that only check “signed in”	Anyone with an account can read everyone’s rows	Check ownership or a role
Leaving a model open to Anyone	You pay for strangers’ use	Servers only, or Signed-in users with a cost cap

​The two kinds of key

​How a request is authenticated

​Scopes

​The scope families

​Presets

​Other limits on a key

​Rules of thumb

​Choosing a key on a server

​Rotating and revoking

​Redirect addresses

​Go-live security checklist

​Common mistakes