Supabase Scoped Tokens: Limit AI Access to One Client Project

Give each client integration its own project-scoped credential, grant only the permissions its job needs, and verify both an allowed operation and a denied one before handoff. A token limited to one project reduces what that credential can reach. It does not prove the AI tool is safe or prevent sensitive information from appearing in its output.

Supabase made scoped personal access tokens generally available on October 6, 2026. Existing account-level tokens continue working, so this is a reason to review your integrations—not evidence that their access changed automatically. Read the announcement.

This guide is for freelancers and small agencies using Supabase's Management API, CLI, or MCP server while building client applications. It is documentation-based guidance, checked October 8, 2026, not a report of a customer incident or a Sentrail product test.

First, identify which credential you are using

A personal access token authenticates development and administration tools. It is different from the project's publishable key used by a web app and from a privileged backend secret key. Changing a PAT does not replace those application keys or repair the app's authorization rules. See Supabase's API key guide.

Before changing anything, record the integration's name, owner, target project, environment, and purpose. Keep the token value out of the record. “Build assistant for Client A staging” is a useful purpose; “all Supabase work” is too broad to review.

Choose permissions from the job

Use the current PAT permission reference to map the operations you need:

Intended task	Documented permission
Inspect project details	Project Settings: Read
Generate database TypeScript types	Database: Read
Fetch security advisors	Advisors: Read
Query project logs	Logs: Read
Apply a migration	Migrations: Read-write

The last row belongs in a separately approved change workflow. It is not a sensible default for an assistant whose job is to explain findings.

At token creation, select the intended project, the necessary permissions, and an expiry that fits the engagement. Supabase says token permissions cannot exceed the creator's current access. Permissions cannot be edited in place; a changed scope requires a replacement token.

Avoid attaching an unrelated client project merely to make a tool's discovery screen work. If an integration cannot operate with the required narrow scope, document that compatibility gap before deciding whether to use it.

Add MCP restrictions when MCP is the connection

The hosted Supabase MCP server normally supports browser-based authentication without a manually created PAT. Scoped PATs are relevant to manual authentication, including CI. Do not replace a functioning OAuth connection simply because a PAT example exists.

For an MCP connection, the documented controls include project_ref, read_only=true, and a restricted features list. Select the project explicitly, expose only the tool groups required, and keep interactive tool approval enabled. Review the MCP setup and security guidance for your client.

Read-only still permits reading. Limit the data an assistant receives, especially logs and query results. An instruction embedded in a support ticket or database value should be treated as untrusted content, not permission to run another action. A prompt asking the assistant to “be careful” is not a substitute for access restrictions.

Verify the boundary without changing customer data

Start with an authorized development project and harmless reads. The PAT documentation supplies a useful two-call check: a token with only Project Settings: Read can fetch that project's details, while the TypeScript-generation endpoint requires Database permission and should return HTTP 403 without it.

Record the observed result, not just the requested settings. Use this handoff table as a worksheet:

Check	Evidence to retain
Required read succeeds	Operation, project reference, timestamp, redacted result
Unneeded read is denied	Operation and actual denial response
Scope matches the engagement	Selected resources and permission names, without the token
Expiry has an owner	Renewal date and responsible person
Tool output stays appropriate	Fields returned and where the output is retained

Do not “test” a denial by attempting a production migration, deletion, or billing change. If a check cannot run safely, label it unverified. These are recommended checks; we have not executed them against your projects.

Replace broad access deliberately

For a planned replacement, identify every job using the old credential, configure the new credential through the integration's secret settings, verify the intended workflow, and retire the old token after confirming its remaining dependencies. Do not assume creating a scoped token invalidates an older one. A suspected compromise needs a separate incident response and urgent containment decision.

CLI caveat: browser-based supabase login creates a classic token. PAT restrictions do not restrict database-password access. Inventory both paths.

Leave the client a usable handoff

Deliver a short record containing the integration owner, authorized project, permitted operations, expiry, evidence locations, and removal procedure. Keep secrets in the client's approved secret store, not in the handoff document. Agree who will renew or remove access when the engagement ends.

Your completion statement should be narrow: “This integration's documented operations were checked with these permissions on this date.” It should not say “the application is secure.” Application authorization remains a separate review; our Supabase RLS launch checklist covers that layer.

For the broader release decision, use Sentrail's launch-readiness methodology to distinguish verified evidence from missing checks. This article does not claim that Sentrail provisions, rotates, or tests scoped PATs automatically.

Prepared with AI assistance and checked against the linked primary documentation. No independent human expert review is claimed.