A personal access token can give a coding agent, CI job, or MCP server access to Supabase projects. The risk is easy to miss: a classic token follows the account’s access, including access to organizations and projects added later. Supabase’s scoped personal access tokens offer a narrower option. You choose the organizations or projects and permissions when creating the token, then use it where the workflow supports a token value.
That can reduce the blast radius of a leaked token, but it also changes setup. Permissions cannot be edited after creation, some commands need more access than others, and the familiar browser login flow still creates a classic token. Before replacing a token in a working build workflow, identify the exact operations it performs and test the scoped token against them.
What changed
Supabase announced general availability of scoped personal access tokens on 6 October 2026. A scoped token can be limited to selected organizations, selected projects within an organization, and specific permissions. You can set an expiry using a preset or a custom date up to one year.
A classic personal access token carries the permissions of the account that created it. That includes current access and access the account may receive later. A scoped token is constrained to the resources and permissions selected at creation, and it cannot grant more than the user’s own access. If that user loses access to a project, the token loses that access too.
The distinction matters when a token is copied into an automation environment. A token used by one project’s deployment job does not necessarily need to see every project in the organization. A token used to inspect configuration may not need write permissions. Scoping lets you express those boundaries in the credential itself rather than relying only on the script not to call other endpoints.
Decide what the automation actually needs
Start with the workflow, not the token form. List the operations the agent or job performs: linking a local repository to a project, reading project settings, changing database objects, or managing another platform resource. Then map each operation to the documented permission it needs.
Do not treat a token described as “read-only” as sufficient until you check every command. For example, the CLI’s project-link flow requires read access to Project Settings, API Keys, and API Key Secrets. A token missing one of those permissions can fail even if the later task only reads data. The error may show up during setup, before the intended job begins.
SQL access has its own boundary. SQL operations are read-only unless the scoped token includes the Database read-write permission. That does not mean every database operation is controlled by the PAT: commands that authenticate directly with a database password are not limited by the token’s scopes. Keep those credential paths separate when reviewing what the automation can do.
For a CI job that only reads one project’s settings, choose that project and the narrowest documented read permissions that let the job run. For a workflow that applies schema changes, include the write permission only if the workflow needs it. Keep human administration on a separate credential. These are permission-design examples; the actual scope depends on the commands and endpoints your workflow uses.
Create a scoped token deliberately
Create the token in Supabase’s dashboard and select the intended resources and permissions before confirming. Supabase shows a review step with the access and risk level. Read that summary as carefully as you would review a production role: confirm the organization and project selection, check each permission, and set an expiry that fits the job’s expected lifetime.
The token value is shown at creation. Store it in your CI secret manager or the appropriate local secret store, and avoid putting it in source code, terminal transcripts, issue comments, or logs. Restrict who can read or change that secret. If you discover that the scope is wrong, create a replacement with the corrected scope and remove the old token after its consumers have moved; the existing token’s permissions cannot be edited in place.
A scoped token can be passed to supported tools using the SUPABASE_ACCESS_TOKEN environment variable or supabase login --token. The browser-based supabase login flow still creates an account-level classic token. Do not assume that using the same CLI means the browser flow will produce the same scope.
There is one operational wrinkle: supabase whoami does not work with project-scoped or organization-scoped tokens. A failed identity check does not by itself mean the credential is invalid. Verify the token with the operation it is meant to authorize, and check that operation’s documented permission requirements.
Roll it out without breaking the build
Treat the change as a credential migration. First identify every consumer of the current token: developer machines, CI workflows, deployment hooks, local agents, and any MCP integration. Replace one consumer at a time with the scoped token, then run the narrowest safe operation that proves it works. Confirm both the expected access and an expected denial outside the selected scope where you can do so without changing production data.
Keep a rollback plan that does not restore an unnecessarily broad token to every consumer. If a job fails, inspect the missing permission and add only the required permission to a newly created scoped token. Since scopes are fixed at creation, permission changes mean issuing a new token and updating the secret-store entry. Record which job owns each token, who can rotate it, and when it expires.
Existing classic tokens continue to work until they expire or are deleted; general availability does not revoke them automatically. That gives teams time to migrate deliberately. It also means unused broad tokens remain a separate cleanup task: inventory them, confirm whether any job still depends on them, and remove obsolete tokens through your normal credential-rotation process.
If your agent needs broad administrative access across many projects, a scoped token may not fit that job. Split the workflow where practical: give routine project work a narrower token and keep exceptional organization-wide actions behind a separate, human-reviewed path. Scope is a control to make access explicit, not a substitute for reviewing the automation itself.
Before rollout, write down a small acceptance check for each consumer: which project it should reach, which operation should succeed, and one out-of-scope operation that should be denied. Use a disposable project or a read-only request for the negative check; do not test by attempting destructive work against production. Keep the result with the workflow documentation so the next person rotating the credential can see why each permission exists. If a job’s requirements change, revisit the scope instead of copying an administrator token into the environment to get past an unexplained permission error.
For the related question of how a database-backed agent workflow passes requests through middleware, see our Supabase MCP pipeline walkthrough. That post covers a different layer of the system; this one is about limiting the platform credential used by automation.
Top comments (1)
tr.ee/dev-to