server-side auth

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Accessing custom claims on server side

For server-side logic, use JWT validation packages appropriate to your framework: express-jwt for Express, koa-jwt for Koa, PyJWT for Python, dart_jsonwebtoken for Dart, or Microsoft.AspNetCore.Authentication.JwtBearer for .NET. These packages decode and validate the JWT to access custom claims.

Metrics API endpoint URL format

Every Supabase project exposes a metrics feed at https://<project-ref>.supabase.co/customer/v1/privileged/metrics. Replace <project-ref> with the identifier from your project URL or from the dashboard sidebar.

Metrics API authentication method

The Metrics API requires HTTP Basic Auth authentication. The username is 'service_role' and the password is a Secret API key (prefixed with sb_secret_). Secret API keys can be created or copied from Project Settings → API Keys.

Metrics API curl test command

To test the Metrics API locally, run: curl <project-url>/customer/v1/privileged/metrics --user 'service_role:sb_secret_...' replacing the secret key with your actual Secret API key.

Metrics API scraping frequency recommendation

Configure your collector to scrape the Metrics API endpoint once per minute. The endpoint emits the full set of metrics on each request.

Long-lived automation tokens for Metrics API

There are two ways to provision long-lived automation tokens for the Metrics API: (1) Create an account access token once at Account Settings > Access Tokens and reuse it wherever you configure observability tooling, or (2) programmatically exchange an access token for project API keys via the Management API.

Exchange access token for project API keys via Management API

You can programmatically exchange an account access token for project API keys using the Management API endpoint: GET https://api.supabase.com/v1/projects/$PROJECT_REF/api-keys?reveal=true with Authorization: Bearer header containing your account access token.

Server-side signInWithOAuth returns endpoint URL

On the server, signInWithOAuth returns data containing a url property instead of redirecting automatically. You must use your server framework's redirect API to redirect to the URL returned in data.url.

PKCE callback route must exchange code for session

At the callback endpoint, extract the authorization code from the query parameter and call supabase.auth.exchangeCodeForSession(code) to complete the OAuth flow and establish the user session.

OAuth flow error handling

If exchangeCodeForSession returns an error, redirect the user to an error page such as /auth/auth-code-error with instructions rather than proceeding with the normal post-authentication flow.

Custom JWT from external auth provider with REST API

If using an external auth provider for authentication instead of Supabase Auth, the external provider can issue a custom JWT with a 'sub' (subject) claim containing the user ID. This JWT is used to authenticate with Supabase REST API, and auth.uid() in RLS policies will correctly reference this user ID from the JWT's sub claim.

createServerClient in Astro uses parseCookieHeader

When creating a Supabase server client in Astro, use createServerClient from @supabase/ssr with cookie handling that calls parseCookieHeader on the request headers and uses Astro.cookies.set() to set cookies in responses.

Astro Supabase client helper implementation

Create a utility file (e.g., src/lib/supabase.ts) with a createClient function that accepts request and cookies from Astro context. The function initializes createServerClient with PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY, and a cookies object that gets cookies from the request header and sets them via Astro.cookies.

Astro getUser checks authentication status

Call supabase.auth.getUser() on the server to retrieve the authenticated user. Returns { data: { user } } where user is null if not authenticated. Use this to redirect unauthenticated users.

Cookie-based auth for Next.js

The Supabase with-next.js template is pre-configured with cookie-based authentication for server-side auth support.

Validate JWT before showing signed-in user in React Native

In React Native apps, use the getClaims method in App.tsx to validate the local JWT before showing the signed-in user. This ensures the authentication token is valid.

Customize email template for token hash

Before implementing server-side authentication, customize the Confirm sign up email template by changing {{ .ConfirmationURL }} to {{ .SiteURL }}?token_hash={{ .TokenHash }}&type=email to support a server-side authentication flow that sends a token hash.

Give your agent this brain