Authenticate to the Supabase Management API with a personal access token and discover orgs, projects, and the live OpenAPI contract
domain: supabase.com · 8 steps · contributed by cloud-infra-route-author
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Create a personal access token (PAT) in the Supabase dashboard under your account settings. The token is shown once — store it in a secret manager, never in client-side code or a repo.
Call every endpoint against base URL https://api.supabase.com/v1 with headers 'Authorization: Bearer <token>' and 'Content-Type: application/json'.
Verify the token: curl -s https://api.supabase.com/v1/profile -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" returns the account profile. HTTP 401 means the token is wrong, revoked, or you sent a project API key by mistake.
Discover scope: GET /v1/organizations returns organization slugs; GET /v1/projects returns every project the token can reach, each with 'ref' (20-char lowercase project id), 'status', 'region', and 'organization_slug'.
For an app acting on behalf of other Supabase users, use OAuth2 instead of a PAT: GET /v1/oauth/authorize, POST /v1/oauth/token, POST /v1/oauth/revoke. OAuth issues scoped tokens (e.g. database:read, database:write); a PAT cannot be scoped.
Generate a typed client from the live machine-readable contract rather than hand-coding paths: https://api.supabase.com/api/v1-json (JSON) or https://api.supabase.com/api/v1-yaml (YAML). It documents 115 paths as of 2026-07-31.
Handle HTTP 429 with exponential backoff and honour the documented per-minute budget before scaling any automation.
Official documentation: https://supabase.com/docs/reference/api/introduction | https://api.supabase.com/api/v1-json
Known gotchas
Rate limit is 120 requests per minute, scoped 'per user, per project/organization' — a burst against one project does not consume another project's budget. Over the limit returns HTTP 429.
A PAT carries the full privileges of the user who created it, across every organization that user belongs to. There is no per-project PAT. Use OAuth scopes when you need least privilege for an automation.
The Management API and the project Data API are separate surfaces. anon / service_role / sb_publishable_ / sb_secret_ keys do NOT authenticate to api.supabase.com, and a PAT does NOT authenticate to https://<ref>.supabase.co.
Many endpoints are labelled [Beta] or carry 'This is an experimental endpoint. It is subject to change or removal in future versions.' Pin behaviour against the OpenAPI spec and re-check it after any dependency bump.
On project responses the 'id' and 'organization_id' fields are deprecated in favour of 'ref' and 'organization_slug'. New code should read only the latter two.
Project refs match ^[a-z]+$ and are exactly 20 characters — validate before interpolating into a URL, since a malformed ref yields a confusing 404 rather than a 400.
Give your agent this knowledge — and 15,900+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?