# Supabase

> Connect Supabase to Tidal Control with a scoped token, so compliance tests can read your organisations' and projects' security settings without table data.

Source: https://tidalcontrol.com/docs/integrations/supabase

Tidal Control's Supabase integration reads security and compliance evidence from your Supabase organisations and projects. It authenticates with a personal access token against the Supabase Management API (`https://api.supabase.com`), and covers organisation access control, end-user authentication policy, public data exposure, encryption in transit, and backup posture.

## What this integration monitors

- **Organisation members:** MFA enrolment per member, and who holds the Owner or Administrator role
- **API keys:** Whether the non-revocable legacy `anon` and `service_role` keys are still in use
- **Storage buckets:** Buckets that serve every object over a public URL
- **Edge functions:** Functions deployed without JWT verification, which are open endpoints on the internet
- **Security advisor:** Supabase's own findings, such as tables in the public schema without row-level security
- **Database:** SSL enforcement, IP allowlist, connection logging, and the row limit on the generated data API
- **Backups:** Point-in-time recovery and the age of the most recent completed backup
- **Authentication:** Password policy, MFA availability, email confirmation, refresh token rotation, access token lifetime, and captcha on sign-up
- **JWT signing keys:** Whether tokens are signed with an asymmetric key rather than the legacy shared secret
- **Preview branches:** Branches created with a copy of production data

Tidal Control reads configuration only. It never queries table rows, saved SQL snippets, or edge function source code.

## Requirements

- Super User role in Tidal Control
- A Supabase account with a role on the organisation you want to assess
- Permission to create access tokens under **Account → Access Tokens**

> **warning:**

**Treat the token as a privileged credential.** The integration needs read access to project API keys so it can report whether legacy keys are still in use. That same permission returns the secret and `service_role` keys, which grant full data access and bypass row-level security. Tidal Control discards the key material and stores only the key type and prefix, but anyone holding the token could retrieve those keys themselves. Create the token from a dedicated service account, not from a personal one.

## Choosing a token

Supabase issues two kinds of personal access token. Both start with `sbp_` and both work, but they differ in what they can reach.

<table>
<thead>
<tr><th>Token type</th><th>Prefix</th><th>Bound to</th></tr>
</thead>
<tbody>
<tr><td><strong>Scoped token</strong> (recommended)</td><td><code>sbp_fc...</code></td><td>The organisations, projects and permissions you choose at creation</td></tr>
<tr><td><strong>Classic token</strong></td><td><code>sbp_...</code></td><td>Everything the issuing account can do, including organisations it joins later</td></tr>
</tbody>
</table>

Prefer a scoped token. It lets you limit the integration to one organisation and to the read permissions listed below. A scoped token can only narrow what the issuing account already has, so the account's own organisation role still sets the ceiling. The weakest role that satisfies every permission is **Read-Only**, which is available on Team and Enterprise plans; on Free and Pro the weakest available role is Developer.

Project API keys (`anon`, `service_role`, `publishable`, `secret`) are a different thing. They reach a project's data plane, not the Management API, and the integration cannot use them.

## Permissions for a scoped token

Grant **Read** on each of the following. Nothing needs Write, and the integration does not request Database, Logs, Edge Function Secrets or SQL Snippets.

<table>
<thead>
<tr><th>Permission (Read)</th><th>Used for</th></tr>
</thead>
<tbody>
<tr><td>Organizations, Organization Settings</td><td>Organisation inventory and plan</td></tr>
<tr><td>Organization Members</td><td>MFA enrolment and roles per member</td></tr>
<tr><td>Projects, Project Settings</td><td>Project inventory, region and service health</td></tr>
<tr><td>Advisors</td><td>Security advisor findings, including row-level security</td></tr>
<tr><td>Network Restrictions, SSL Enforcement</td><td>Database network and transport checks</td></tr>
<tr><td>Database Backups</td><td>Point-in-time recovery and backup freshness</td></tr>
<tr><td>Auth Config, Auth Signing Keys</td><td>Authentication policy and JWT signing keys</td></tr>
<tr><td>Storage</td><td>Public bucket check</td></tr>
<tr><td>Edge Functions</td><td>JWT verification check</td></tr>
<tr><td>API Keys</td><td>Legacy key check</td></tr>
<tr><td>Data API Config, Database Config</td><td>Row limit and connection logging</td></tr>
<tr><td>Production Branches</td><td>Preview branch data check</td></tr>
</tbody>
</table>

A missing permission does not stop the whole run. The checks that depend on it fail with an authorisation error, and the rest continue.

## Configuration step-by-step plan

We'll create a personal access token in the Supabase dashboard, then add the connection in Tidal Control. Choose a scoped token when it is available to your account.

**Configuration steps:**

1. **Create a personal access token**
2. **Configure the integration in Tidal Control**

## Step 1: Create a personal access token

- Sign in to the [Supabase dashboard](https://supabase.com/dashboard) with the service account
- Go to **Account → Access Tokens**, or open https://supabase.com/dashboard/account/tokens directly
- Click **Generate new token** and name it, for example `Tidal Control`
- If permission selection is available, choose a **scoped** token, select the organisation to assess, and grant the Read permissions from the table above
- If permission selection is missing, scoped tokens are not yet enabled for your account. [Request early access from Supabase](https://supabase.help), or create a classic token using the dedicated service account. A classic token has all of that account's permissions across every organisation it belongs to
- Check the token's expiry and plan to rotate it before that date
- **Copy the token immediately**: it is shown only once

> **warning:**

**The token is shown once.** If you close the dialog without copying it, revoke it and generate a new one.

## Step 2: Configure the integration in Tidal Control

- Go to **Settings → Integrations** in Tidal Control
- Click the **plus icon** next to **Supabase**
- Fill in the configuration:
  - **Name:** A descriptive name, for example `Supabase`
  - **Personal access token:** The `sbp_...` token from step 1
- Click **"Create"** to save the integration

## Configuration fields explained

The integration dialog asks for the following values:

**Name:**
- A descriptive name for this connection
- For example: `Supabase`, `Supabase Production`

**Personal access token:**
- The scoped or classic token from step 1, starting with `sbp_`
- Required, and stored as a secret
- No organisation or project ID is needed. The token identifies the organisations it can reach

## Verification

The integration is working when all of the following are true:

- Settings → Integrations shows Supabase under **Configured Integrations**
- Supabase tests are available in the Tests section
- Test refresh delivers results without authentication errors

## Frequently asked questions

**Do I need an organisation or project ID?**
No. A scoped token already carries the organisations you selected, and a classic token reaches every organisation the account belongs to.

**Can Tidal Control see the data in my database?**
No. The integration reads the Management API, which exposes configuration. It never queries tables, saved SQL snippets or edge function source, and it never requests the Database or SQL Snippets permissions.

**Why do the network restriction and point-in-time recovery tests fail on my Free-plan organisation?**
Both are paid entitlements. On a Free plan the endpoints report the feature as unavailable, and the tests fail because the protection is absent, whichever the reason. The organisation plan is recorded in the evidence so a reviewer can tell an entitlement gap from a misconfiguration.

**What happens to paused projects?**
A paused project still appears in the inventory, but it answers few per-project endpoints and contributes no buckets, functions or advisor findings. Read absence against the project status rather than as a pass.

**How do I rotate the token?**
Supabase supports a custom expiry for personal access tokens. Check the expiry configured for your token and rotate it before that date to keep evidence collection running. Generate a new token, update the connection in Tidal Control, then revoke the old one. Revoking one token does not affect others.

## Common problems

**"Personal access token is required"**
- The field is empty, or the copied value was lost. Generate a new token

**Authentication error on every test**
- The token is wrong, expired, revoked or malformed. Check its expiry and replace it if it has expired. Check that it starts with `sbp_` and is a personal access token, not a project `anon` or `service_role` key

**Some tests fail with an authorisation error while others pass**
- The scoped token is missing a Read permission from the table above, or the account's organisation role is too weak. Add the permission, or issue the token from an account with at least the Read-Only role

**A project shows no buckets, functions or advisor findings**
- Either the project has none, or it is paused. Check the project status in the Supabase dashboard

### Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

> **info:**

**Gather support info:** Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.