Skip to content

Platform

Third-party auth

Tested with:supabase-js 2 · PostgREST 13

You do not have to move your users to use Databasezy. Trust your current auth provider’s JWTs and send them to the project endpoint as the user’s token: the edge verifies them with the provider’s public keys and your row-level security policies see their claims.

  1. Make the provider’s tokens carry the role. A role claim (or the claim you name) of authenticated or anon is used as is; anything else, or no claim, gets the issuer’s default role (authenticated unless you choose anon). A third-party token is never service_role, whatever it claims.

  2. Add the issuer in Platform services → Auth → Third-party auth, or with the API. Every issuer needs the audience (aud) its tokens are issued for, because one tenant of these providers signs tokens for all its applications:

    shell
    # Clerk: the Frontend API domain
    zb api POST /v1/orgs/{org}/projects/<project-id>/auth/third-party -d '{
    "kind": "clerk", "domain": "clerk.example.com", "audiences": ["https://app.example.com"]
    }'
    # Auth0: the tenant domain and the API identifier; a namespaced role claim
    zb api POST /v1/orgs/{org}/projects/<project-id>/auth/third-party -d '{
    "kind": "auth0", "domain": "tenant.us.auth0.com", "audiences": ["https://api.example.com"],
    "role_claim": "https://example.com/role"
    }'
    kindFieldsIssuerKeys
    clerkdomainhttps://<domain>https://<domain>/.well-known/jwks.json
    auth0domainhttps://<domain>/https://<domain>/.well-known/jwks.json
    firebasefirebase_project_idhttps://securetoken.google.com/<id>Google’s securetoken keys; the audience defaults to the project id
    cognitoregion, user_pool_idhttps://cognito-idp.<region>.amazonaws.com/<pool>the pool’s /.well-known/jwks.json; an access token’s client_id counts as its audience
    workosclient_idhttps://api.workos.com/user_management/<client>https://api.workos.com/sso/jwks/<client>
    oidcissuer, optional jwks_urlthe iss of its tokensfrom its OpenID configuration unless jwks_url
  3. Send the provider’s token from your app as the user’s token, with your publishable key:

    lib/db.ts
    const supabase = createClient(DATABASEZY_URL, DATABASEZY_PUBLISHABLE_KEY, {
    accessToken: async () => (await clerk.session?.getToken()) ?? null,
    });

The user id of a third-party token is its sub, which is usually not a UUID, so compare it as text instead of using auth.uid():

SQL
create policy "own notes" on notes
for select to authenticated
using (owner_id = (auth.jwt() ->> 'sub'));

Every claim of the token is in auth.jwt() (for example Clerk’s org_id), except the claims the edge sets itself.

For an issuer the platform cannot reach (a private network, an air-gapped identity provider) paste its public keys instead of a key URL: "jwks": {"keys": [...]} in place of jwks_url, 1 to 10 keys with a kid (RSA 2048 to 8192 bits, EC P-256 or P-384, Ed25519), at most 16 KiB. Only public members are kept; a key with private material is refused and not stored. Inline keys are never fetched, so when the issuer rotates its keys, add the new set as a new issuer and remove the old one.

  • Asymmetric signatures only (RS256, RS384, RS512, PS256, ES256, ES384, EdDSA), a kid the issuer’s key set knows, exp (30 s clock leeway), nbf and iat, the exact iss, one of the audiences and a sub.
  • Key sets are fetched through the platform’s outbound guard (https, public addresses only), cached for 10 minutes and refreshed at most every 30 s when a token names an unknown key.
  • A third-party token reaches the data API, storage and realtime; it is refused on /auth/v1, where it is not one of your project’s own users.
  • Adding an issuer is a high-severity security event in your audit log: it opens your project’s data to whoever can get a token from that issuer. Removing it stops its tokens as soon as the edge sees the change.

Up to 10 issuers per project and 10 audiences per issuer.