Supabase dashboard integration

The CipherStash dashboard can connect to your Supabase account with OAuth, guide Stack onboarding for a specific project, and register Supabase as an OIDC provider for identity-aware encryption.

Use this when you want a guided setup path instead of configuring everything from the CLI alone.

Where to find it

In the CipherStash Dashboard:

1. Open a workspace
2. Go to Settings → Integrations
3. Click Connect Supabase (or Open setup if already connected)

Connected workspaces also have a dedicated setup page at:

/workspaces/{workspaceId}/settings/integrations/supabase

Connect Supabase (OAuth)

The dashboard uses Supabase OAuth with PKCE. Tokens are encrypted at rest in the CipherStash database and scoped to the workspace you connect from.

OAuth scopes

The integration requests these Supabase OAuth scopes:

Configure these scopes on your Supabase OAuth app. The dashboard does not request secrets:read.

Setup hub

After connecting, the setup hub helps you onboard a specific Supabase project with Stack.

Project selection

The hub lists Supabase projects available to the connected account. Select the project you want to encrypt. Readiness checks and onboarding commands update when you change projects.

If you arrived from the Supabase Marketplace with a pre-selected project, that project is chosen automatically via a ?project= query parameter.

Readiness checks

For the selected project, the dashboard verifies:

When project health, EQL, and OIDC are all satisfied, the hub shows a Stack-ready badge.

Configure OIDC from the dashboard

If Supabase OIDC is not registered yet, click Configure OIDC for this project on the readiness panel.

The dashboard registers a Supabase OIDC provider on your CipherStash workspace with issuer:

https://{projectRef}.supabase.co/auth/v1

This enables identity-aware encryption with Supabase Auth JWTs via LockContext.

See OIDC Providers for manual registration and usage from code.

Stack onboarding commands

The hub copies the official Supabase + Stack workflow:

npm install @cipherstash/stack
npm install -D stash
npx stash auth login
npx stash init --supabase
npx stash db install --supabase --migration

It also generates a .env.local snippet for the selected project, including:

• DATABASE_URL (Postgres host db.{projectRef}.supabase.co)
• SUPABASE_URL and SUPABASE_ANON_KEY (when available from the Management API)
• Comments for local dev (~/.cipherstash/) vs production (CS_* access keys)

For the full CLI and SDK path, see Supabase.

Encrypted schema

When the selected project already has eql_v2_encrypted columns, the hub lists them by schema, table, and column name.

Install from the Supabase Marketplace

CipherStash supports the Supabase partner integration guide for the Install Integration button in the Supabase Marketplace.

There are two redirect methods. Both create a one-time install record and send the user to a handler page where they pick a CipherStash workspace and complete OAuth.

Method 1 — Simple redirect

Supabase redirects the user to:

GET {APP_URL}/api/integrations/supabase/install?project_id={ref}&organization_slug={slug}

The API creates an install record and redirects to:

{APP_URL}/integrations/supabase/install/{integrationId}

Method 2 — Signed redirect

Supabase POSTs a signed JWT to the same install endpoint:

POST {APP_URL}/api/integrations/supabase/install
Content-Type: application/json

{ "token": "<signed-jwt>" }

On success, the API returns:

{
  "integrationId": "...",
  "redirectUrl": "{APP_URL}/integrations/supabase/install/{integrationId}",
  "expiresAt": "..."
}

Supabase redirects the user to redirectUrl.

Install handler flow

1. User lands on /integrations/supabase/install/{integrationId}
2. If not signed in to CipherStash, they authenticate first
3. User selects the workspace where Supabase should be connected
4. OAuth completes and binds the install record to that workspace (bind-once)
5. User lands on the setup hub, optionally with the Supabase project pre-selected

Install links expire. If a link is invalid or expired, return to Supabase and click Install Integration again.

Production configuration (CipherStash operators)

These environment variables configure the dashboard deployment (for example on Vercel):

NEXT_PUBLIC_APP_URL="https://dashboard.cipherstash.com"

# Supabase OAuth (Connect button)
SUPABASE_OAUTH_CLIENT_ID="..."
SUPABASE_OAUTH_CLIENT_SECRET="..."
# Optional — defaults to {NEXT_PUBLIC_APP_URL}/api/integrations/supabase/callback
# SUPABASE_OAUTH_REDIRECT_URI="..."

# Supabase Marketplace signed redirect (Method 2)
SUPABASE_PARTNER_JWT_AUDIENCE="https://dashboard.cipherstash.com"
SUPABASE_PARTNER_JWT_PUBLIC_KEYS='{"pik_xxx":"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"}'

Register the OAuth callback URL on your Supabase OAuth app:

{NEXT_PUBLIC_APP_URL}/api/integrations/supabase/callback

Values to provide Supabase (Marketplace)

Verify signed redirect is enabled:

curl -I https://dashboard.cipherstash.com/api/integrations/supabase/install

When JWT verification is configured, the response includes:

X-Supabase-Partner-Signed-Redirect: enabled

Database migrations

The dashboard requires these migrations:

• supabase_integrations — encrypted OAuth tokens per workspace
• supabase_partner_installs — one-time Marketplace install records
• supabase_oauth_sessions — PKCE OAuth state keyed by state

Apply them before enabling the integration in production.

Security notes

• OAuth tokens are encrypted at rest; integration queries run under organization RLS
• Partner install IDs bind to a single workspace on first use (prevents hijacking)
• OAuth PKCE state is stored in the database keyed by OAuth state (multi-tab safe)
• Sign-in and sign-up redirects are validated as internal paths only
• NEXT_PUBLIC_APP_URL is required in production (Host header is not trusted)
• Public install endpoints are rate limited
• Partner JWTs are verified with ES256, a 5-minute max age, and required claims

Next steps

• Supabase — CLI setup, EQL install, and SDK integration paths
• Supabase JS SDK integration — encryptedSupabase API reference
• OIDC Providers — Register and use identity providers
• Identity-aware encryption — Bind encryption to user JWTs
• Going to production — CS_* credentials for deployed apps