Supabase token guidance separates Database read from full-account CLI access

Supabase’s October 26 guidance on Personal Access Tokens explains a distinction that matters when a coding agent needs to inspect one database: a broad Read‑only preset can still include secrets such as API keys. A token limited to Database read answers a narrower job.

This is detailed guidance for an existing feature. Supabase says token scoping became generally available on September 28 and was announced at Supabase Select on October 2. The October 26 post is not the first launch of scoped tokens.

For its example agent, Supabase recommends choosing one project, starting from No access, then enabling Database read. It says that permission covers listing tables, generating types and running read‑only SQL. A deployment script that needs to change resources would require a different permission selection. The useful question is what the tool needs to do, rather than whether the preset’s name sounds restrictive.

The guidance says the Management API and MCP server can use a scoped token. Missing Management API permissions produce a 403 response identifying the missing permission; a project outside the token’s resource scope receives a plain 403. MCP tools check permissions before execution. With Database read, an SQL write through the documented execute_sql path returns a Postgres permission error rather than an HTTP 403; migrations require a separate permission.

The CLI has an important exception to the new Dashboard default. Supabase says the browser flow for supabase login still creates a full‑account token, with a scoped selection planned. Its documented alternative is to create a scoped token in the Dashboard and pass it using supabase login --token. For CI, SUPABASE_ACCESS_TOKEN overrides locally saved tokens.

Those are descriptions of the current credential paths, not a claim that every login now creates a scoped token. OpenTools has not created a token, logged in or tested the enforcement.

Supabase [explicitly warns](https://supabase.com/blog/scope‑your‑personal‑access‑tokens) that database commands relying on `SUPABASE_DB_PASSWORD` bypass token permissions entirely. Restricting the PAT therefore does not establish that every database command in the same workflow is restricted by that token. The credential used by the command matters. There is also a dependency when a CI workflow includes `supabase link`: the post says its token needs read access to Project Settings, API Keys and API Key Secrets. That requirement should be considered before treating the minimal Database‑read example as sufficient for an entire pipeline. A team reviewing an agent integration needs to distinguish the Management API or MCP permission check from a command using the database password. Putting both in one script does not turn them into one authorization mechanism.

According to Supabase, every token request evaluates both the token’s scope and the user’s current role. Losing organizational access or a database‑read permission removes the corresponding token access; restoring that user access can make the token work again. A permission selected on a token does not supply a permission the user lacks. These are the provider’s enforcement descriptions, not an independent security audit.

Scopes and permissions are fixed when a token is created. Changing them requires a replacement token. Existing full‑account tokens are labelled Legacy, but the post gives no deprecation or shutoff date: they continue until expiration or deletion. Creating a narrower token does not, by itself, retire a broader token already in use.

The practical review is therefore broader than selecting a preset: identify the project and operations, check the credential each tool actually uses, and account for any existing full‑access token separately.

AI‑generated editorial illustration by OpenTools Team, based on Supabase’s October 26 guidance. The two paths distinguish a scoped Personal Access Token from commands using a database password: Supabase says SUPABASE_DB_PASSWORD commands bypass PAT permissions. This is a conceptual metaphor, not Supabase product UI, a technical architecture diagram or a tested security‑control claim. Both are legitimate credential paths; the illustration does not establish the database permissions held by either.