Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: describe personal access tokens as scoped (#52217)

Wen Bo Xie61058a579aae
diff --git a/apps/docs/content/guides/ai-tools/mcp.mdx b/apps/docs/content/guides/ai-tools/mcp.mdx
index 94fd2bf7e04..ab31b481d02 100644
--- a/apps/docs/content/guides/ai-tools/mcp.mdx
+++ b/apps/docs/content/guides/ai-tools/mcp.mdx
@@ -213,7 +213,7 @@ There are some situations where you might want to manually authenticate the MCP
### CI environment
-To authenticate the MCP server in a CI environment, create a scoped personal access token (PAT) and pass it as a header to the MCP server.
+To authenticate the MCP server in a CI environment, create a personal access token (PAT) and pass it as a header to the MCP server.
1. Production projects can contain sensitive data. Before connecting one, scope the server to that project, enable [read-only mode](#configuration-options), restrict the available feature groups, and review the [security risks](#security-risks).
diff --git a/apps/docs/content/guides/deployment/managing-environments.mdx b/apps/docs/content/guides/deployment/managing-environments.mdx
index c9ecafb560b..84d961ea9fa 100644
--- a/apps/docs/content/guides/deployment/managing-environments.mdx
+++ b/apps/docs/content/guides/deployment/managing-environments.mdx
@@ -161,7 +161,7 @@ You need a _new_ project for staging. A project which has already been modified
The Supabase CLI requires a few environment variables to run in non-interactive mode.
-- `SUPABASE_ACCESS_TOKEN` is a [scoped personal access token](/docs/guides/platform/personal-access-tokens) limited to the projects this workflow deploys to
+- `SUPABASE_ACCESS_TOKEN` is a [personal access token](/docs/guides/platform/personal-access-tokens) scoped to the projects this workflow deploys to
- `SUPABASE_DB_PASSWORD` is your project specific database password
- `SUPABASE_PROJECT_ID` is your project specific reference string
diff --git a/apps/docs/content/guides/getting-started/api-keys.mdx b/apps/docs/content/guides/getting-started/api-keys.mdx
index a6676ca6cda..d6dc39f9b07 100644
--- a/apps/docs/content/guides/getting-started/api-keys.mdx
+++ b/apps/docs/content/guides/getting-started/api-keys.mdx
@@ -176,7 +176,7 @@ Pass the branch's own project ref to read the keys for a preview branch. A branc
Use the Management API to fetch keys from your own tooling, such as a deploy script or an internal provisioning service.
-Authenticate with a [personal access token](/dashboard/account/tokens). An OAuth application needs the `secrets:read` scope, and a [scoped personal access token](/docs/guides/platform/personal-access-tokens) needs the **API Keys** permission with **Read** access. To reveal key values with `reveal=true`, as the example below does, the scoped token also needs **API Key Secrets** with **Read** access. Without the required scope or permissions, the request returns 403 Forbidden.
+Authenticate with a [personal access token](/dashboard/account/tokens). An OAuth application needs the `secrets:read` scope. A personal access token [you've scoped](/docs/guides/platform/personal-access-tokens) needs the **API Keys** permission with **Read** access. To reveal key values with `reveal=true`, as the example below does, the token also needs **API Key Secrets** with **Read** access. Without the required scope or permissions, the request returns 403 Forbidden.
```bash
export PROJECT_REF="your-project-ref"
diff --git a/apps/docs/content/guides/platform/personal-access-tokens.mdx b/apps/docs/content/guides/platform/personal-access-tokens.mdx
index 98de3ea3636..371d23fba52 100644
--- a/apps/docs/content/guides/platform/personal-access-tokens.mdx
+++ b/apps/docs/content/guides/platform/personal-access-tokens.mdx
@@ -3,28 +3,29 @@ title: 'Personal Access Tokens'
description: 'Scope personal access tokens to specific organizations, projects, and permissions'
---
-Personal access tokens (PATs) authenticate you to the [Management API](/docs/reference/api/introduction) and the tools built on it, like the Supabase CLI and the [MCP server](/docs/guides/ai-tools/mcp). They come in two flavors:
+Personal access tokens (PATs) authenticate you to the [Management API](/docs/reference/api/introduction) and the tools built on it, like the Supabase CLI and the [MCP server](/docs/guides/ai-tools/mcp).
-- **Classic tokens**, shown with a **Legacy** badge in the dashboard, 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.
+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.
<Admonition type="note">
-We recommend scoped tokens for everything, especially AI agents, automation scripts, and CI environments. If a token leaks, the blast radius stays small.
+We recommend scoping every token, especially tokens for AI agents, automation scripts, and CI environments. If a token leaks, the blast radius stays small.
</Admonition>
-To use scoped personal access tokens you need a Supabase 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](/docs/guides/platform/access-control)), granting that permission to a token has no effect: the token still can't do it.
+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](/docs/guides/platform/access-control)), granting that permission to a token has no effect.
-You create scoped tokens the same way as classic tokens, from your [access tokens](/dashboard/account/tokens) settings. Choose which permissions to grant during creation instead of leaving the token with full access.
+You create and scope tokens from your [access tokens](/dashboard/account/tokens) settings.
-## Create and use a scoped personal access token
+## 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. Both calls are reads available to every organization role, including Read-Only, so anyone can run 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](/dashboard/account/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 (scoped personal access tokens start with `sbp_fc`) and use it against the Management API, replacing `your-project-ref` with the project's ref:
+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:
```bash
export SUPABASE_ACCESS_TOKEN="sbp_fc..."
@@ -34,7 +35,7 @@ curl "https://api.supabase.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
+# Denied: the token lacks the Database permission this endpoint needs
curl -i "https://api.supabase.com/v1/projects/your-project-ref/types/typescript" \
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
# Returns HTTP 403
@@ -42,9 +43,9 @@ curl -i "https://api.supabase.com/v1/projects/your-project-ref/types/typescript"
To grant exactly what a workflow needs, see [Permission scopes](#permission-scopes) for the permission each endpoint requires and [MCP tools](#mcp-tools) for the permission each MCP tool requires.
-## Use a scoped personal access token with the Supabase CLI
+## Use a token with the Supabase CLI
-The browser flow of `supabase login` creates a classic token. To run the CLI with a scoped token instead, set it in the `SUPABASE_ACCESS_TOKEN` environment variable, or save it with `supabase login --token`. The environment variable takes precedence over any saved token, which also makes it the right choice for CI.
+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:
@@ -59,12 +60,12 @@ Database commands that connect with your database password, such as `supabase db
## 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.
+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.
<$Partial path="access-control/scoped_pat_permissions.mdx" />
## MCP tools
-A scoped personal access token used to authenticate the [MCP server](/docs/guides/ai-tools/mcp) can only call the tools its granted permissions unlock. See [Available tools](/docs/guides/ai-tools/mcp#available-tools) for what each tool does.
+A token used to authenticate the [MCP server](/docs/guides/ai-tools/mcp) can only call the tools its granted permissions unlock. See [Available tools](/docs/guides/ai-tools/mcp#available-tools) for what each tool does.
<$Partial path="access-control/scoped_pat_mcp_tools.mdx" />
diff --git a/apps/docs/spec/sections/generateAccessControlPartials.mts b/apps/docs/spec/sections/generateAccessControlPartials.mts
index ccc3ac83a20..40cc9be62eb 100644
--- a/apps/docs/spec/sections/generateAccessControlPartials.mts
+++ b/apps/docs/spec/sections/generateAccessControlPartials.mts
@@ -302,7 +302,7 @@ function generateMcpToolsPartial(tools: McpMap, outputPath: string) {
const requirement = publishable.some((group) => group.length === 0)
? 'None (always available)'
: publishable.length === 0
- ? 'Not available to scoped personal access tokens'
+ ? 'Not available to personal access tokens with a scope'
: formatRequirement(publishable)
return `| \`${tool}\` | ${requirement} |`
})