Personal access tokens (PATs) authenticate you to the Management API and the tools built on it, like the Zuvo CLI and the MCP server. They come in two flavors:
- Classic tokens carry your account's full access. That means every permission, on every organization and every project you belong to today, and on every one you create or join in the future. A classic token created a year ago can touch a project you created today.
- Scoped tokens carry only the organizations, projects, and permissions you choose. For example: read one project's database and view its logs, with no access to billing or organization settings.
To use scoped personal access tokens you need a Zuvo account with a role on the organization or project you want the token to reach. A scoped personal access token's permissions only ever narrow what your account can already do. They never grant more. If your role doesn't include a permission (see Access Control), granting that permission to a token has no effect: the token still can't do it.
You create scoped tokens the same way as classic tokens, from your access tokens settings. Choose which permissions to grant during creation instead of leaving the token with full access.
Create and use a scoped personal access token
This example creates a token that can only read one project's settings, then calls an endpoint outside that scope. Both calls are reads available to every organization role, including Read-Only, so anyone can run it.
- Go to your access tokens settings and generate a new token.
- While creating it, scope the token to one project and grant only the Project Settings permission with Read access.
- Copy the token (scoped personal access tokens start with
sbp_fc) and use it against the Management API, replacingyour-project-refwith the project's ref:
export SUPABASE_ACCESS_TOKEN="sbp_fc..."
# Allowed: Project Settings Read unlocks this endpoint
curl "https://api.zuvodev.com/v1/projects/your-project-ref" \
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
# Returns the project's details
# Denied: this endpoint needs the Database permission, which the token lacks
curl -i "https://api.zuvodev.com/v1/projects/your-project-ref/types/typescript" \
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
# Returns HTTP 403
The tables below list which permission unlocks which endpoints, and which permission each MCP tool requires, so you can grant exactly what a workflow needs.
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 creating a scoped personal access token. Permissions that currently 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 scoped personal access token used to authenticate the MCP server can only call the tools its granted permissions unlock. See Available tools for what each tool does.
| MCP tool | Required permission |
|---|---|
apply_migration | Migrations (Read-write) |
confirm_cost | None (always available) |
create_branch | Development Branches (Read-write) or Production Branches (Read-write) |
create_project | Organization Projects (Read-write) |
delete_branch | Production Branches (Read-write) or Development Branches (Read-write) |
deploy_edge_function | Edge Functions (Read-write) |
execute_sql | Database (Read) |
generate_typescript_types | Database (Read) |
get_advisors | Advisors (Read) |
get_cost | Organization Settings (Read) and Projects (account-wide) (Read) |
get_edge_function | Edge Functions (Read) |
get_logs | Logs (Read) |
get_organization | Organization Settings (Read) |
get_project | Project Settings (Read) |
get_project_url | Project Settings (Read) |
get_publishable_keys | API Keys (Read) |
get_storage_config | Storage Config (Read) |
list_branches | Development Branches (Read) or Production Branches (Read) |
list_edge_functions | Edge Functions (Read) |
list_extensions | Database (Read) |
list_migrations | Migrations (Read) |
list_organizations | Organizations (Read) |
list_projects | Projects (account-wide) (Read) |
list_storage_buckets | Storage (Read) |
list_tables | Database (Read) |
merge_branch | Production Branches (Read-write) or Development Branches (Read-write) |
pause_project | Project Settings (Read-write) |
query_logs | Logs (Read) |
rebase_branch | Production Branches (Read-write) or Development Branches (Read-write) |
reset_branch | Production Branches (Read-write) or Development Branches (Read-write) |
restore_project | Project Settings (Read-write) |
search_docs | None (always available) |
update_storage_config | Storage Config (Read-write) |
Footnotes
-
Requires Project Settings (Read) and Database (Read). ↩ ↩2 ↩3 ↩4
-
Requires Organization Settings (Read-write) and Project Settings (Read-write). ↩ ↩2
-
Requires Auth Config (Read-write) and Project Settings (Read-write). ↩ ↩2
-
Requires Project Settings (Read-write) and Database (Read-write). ↩ ↩2
-
Requires Database Config (Read), Database (Read), SSL Enforcement (Read), Network Restrictions (Read), Auth Config (Read), Data API Config (Read), Realtime Config (Read), and Storage Config (Read). ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8