Connect Supabase

An account of Supabase is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Postgres, storage, auth and edge functions of Supabase projects, through the Management API.

One account is your company's Supabase OAuth app authorised on an organisation, or a personal access token; one resource is one project (database, storage, auth and edge functions). Supabase runs one project per environment, so the owner of the account labels each project (staging, prod, …) and the permissions tied to an environment apply to the projects carrying that label.

Permissions, presets and tools of this service: Supabase plugin.

How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (providers.<id>.*, see configuration keys). Every instance registers its own app: this gateway never uses an app shared with another one.

The usual way: through your company's OAuth app at the service (one click once the app is registered)

Scopes asked: all.

Another way: with a personal access token pasted by hand

1. Sign in to Supabase as the account the agents will act as.
2. Open Account preferences, Access tokens, then generate a new token.
3. Make it a scoped token: pick the organisation and only the projects the missions need.
4. Grant the permissions below, choose an expiry, and generate the token.
5. Copy the token and paste it here. Supabase shows it once.

Where: https://supabase.com/dashboard/account/tokens

Permissions to grant at the service, and no more:

• Project Settings: read
• API Keys: read
• API Key Secrets: read
• Database: read
• Migrations: read-write
• Advisors: read
• Storage Config: read
• Storage Config: read-write
• Auth Config: read
• Auth Config: read-write
• Edge Functions: read
• Edge Functions: read-write
• Secrets: read
• Secrets: read-write

Recommended expiry: 90 days.

What the connect page asks:

• Personal access token (secret): Prefer a scoped token: it reaches only the projects and permissions you chose.

The service's documentation: https://supabase.com/docs/guides/platform/personal-access-tokens

Disconnecting

Revoke your company's OAuth app in the settings of the Supabase organisation, under the authorised OAuth apps.

Registration notes from the plugin

From the plugin's README, written for the people who register the app or create the token.

Credential — the company's Supabase OAuth app

credential.kind: 'oauth2', refreshable: true :

Registering the app (once per company)

1. In the Supabase dashboard, open your organization → OAuth Apps (https://supabase.com/dashboard/org/<slug>/apps) and create an app.
2. Set the redirect URL to the callback the instance shows in Settings → Administration → Company apps (it is derived from the instance public_url).
3. Pick the scopes the company is ready to grant the gateway. The plugin needs database:read for the read-only tools, database:write for migrations, secrets:read for the data-plane tools (it reads the project service_role key through the Management API), and the auth, storage, edge_functions, environment, organizations and projects scopes for the corresponding tools and for discovery.
4. Enter the client id and client secret in the instance configuration (Settings → Administration → Company apps). The host uses them for the authorization-code flow and for refresh ; the plugin reads neither, and nothing from the environment.

Connecting is then one click : the host runs the authorization-code flow from the spec above and stores the token pair encrypted. Access tokens live one hour ; the host refreshes them with the standard refresh_token grant and HTTP Basic client authentication (the refresh token rotates), and owns the refresh timing. A 401/403 upstream throws UpstreamAuthError, which also triggers a refresh in the host.

Resource discovery

discoverResources lists GET /v1/organizations and GET /v1/projects and returns one Resource per project : ref = project ref, displayName = <organization> / <project>, metadata = organization, region, status. The Management API returns the whole list (no paging) ; the plugin caps it at MAX_DISCOVERED_PROJECTS (200) and warns through the logger. The owner labels each project's env on the account's page (Accounts).

Credential, the other way: a personal access token

Without a company OAuth app — or beside it — an account is connected with a personal access token pasted by hand (supabaseTokenCredential, src/token.ts). Create it at https://supabase.com/dashboard/account/tokens, as the account the agents will act as (a shared service account is fine), scoped to the organisation and projects the missions need, with the permissions the connect page lists (guide.permissions) and an expiry. Every tool runs with it. The gateway checks it with GET /v1/organizations and seals it; Supabase exposes no expiry and no deletion endpoint for these tokens, so removing the account tells the person to delete it under Account preferences → Access tokens. ADR token-connections-beside-the-integration-app.

Last changed 2026-10-16. This page as Markdown: /docs/providers/supabase.md