Personal Access Tokens

Personal access tokens (PATs) authenticate you to the Management API and the tools built on it, like the Supabase CLI and the MCP server.

When you create a token, you scope it to the organizations, projects, and permissions it needs. For example, a token can read one project's database and view its logs without touching billing or organization settings. Tokens you create in the Supabase Dashboard are scoped by default.

You can still create a token with your account's full access. The Dashboard shows these tokens with a Legacy badge. A token with full access carries every permission on every organization and project you belong to, including ones you create or join later. A full-access token created a year ago can touch a project you created today.

To scope a token you need a Supabase account with a role on the organization or project you want the token to reach. A token's permissions narrow what your account can already do and never grant more. If your role doesn't include a permission (see Access Control), granting that permission to a token has no effect.

You create and scope tokens from your access tokens settings.

Scope a token and use it#

This example creates a token that can only read one project's settings, then calls an endpoint outside that scope. Because both calls are reads that every organization role can make, including Read-Only, anyone can run the example.

1. Go to your access tokens settings and generate a new token.
2. While creating it, scope the token to one project and grant only the Project Settings permission with Read access.
3. Copy the token (tokens created with a scope start with sbp_fc) and use it against the Management API, replacing your-project-ref with the project's ref:

1
export SUPABASE_ACCESS_TOKEN="sbp_fc..."
2
3
# Allowed: Project Settings Read unlocks this endpoint
4
curl "https://api.supabase.com/v1/projects/your-project-ref" \
5
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
6
# Returns the project's details
7
8
# Denied: the token lacks the Database permission this endpoint needs
9
curl -i "https://api.supabase.com/v1/projects/your-project-ref/types/typescript" \
10
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
11
# Returns HTTP 403

To grant exactly what a workflow needs, see Permission scopes for the permission each endpoint requires and MCP tools for the permission each MCP tool requires.

Use a token with the Supabase CLI#

The browser flow of supabase login creates a token with your account's full access. To run the CLI with a token you scoped in the Dashboard instead, set it in the SUPABASE_ACCESS_TOKEN environment variable or save it with supabase login --token. Because the environment variable takes precedence over any saved token, it's the right choice for CI.

For example, with a token granted Projects (account-wide) with Read access, supabase projects list lists the projects the token can reach:

1
export SUPABASE_ACCESS_TOKEN="sbp_fc..."
2
supabase projects list

Commands that call the Management API fail with a permission error when the token lacks the required permission. supabase link, for instance, needs Project Settings, API Keys, and API Key Secrets, all with Read access.

Database commands that connect with your database password, such as supabase db push with SUPABASE_DB_PASSWORD set, aren't limited by the token's permissions. A workflow that runs supabase link before supabase db push still needs the permissions supabase link requires.

Permission scopes#

Each permission controls read or read-write access to one resource, for example Database, Edge Functions, or Production Branches. The permissions and names below match those shown when you create a token. Permissions that unlock neither a public Management API endpoint nor an MCP tool are omitted. A few endpoints need more than one permission. The footnotes call these out.

MCP tools#

A token used to authenticate the MCP server can only call the tools its granted permissions unlock. See Available tools for what each tool does.