The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: update edge functions integration guides with new server package (#45058)
Tomás Pozo75aa1b9e4044
diff --git a/apps/docs/content/guides/functions/auth.mdx b/apps/docs/content/guides/functions/auth.mdxindex 13895c1946b..9ad4e83383b 100644--- a/apps/docs/content/guides/functions/auth.mdx+++ b/apps/docs/content/guides/functions/auth.mdx@@ -1,100 +1,304 @@---id: 'auth'title: 'Securing Edge Functions'-description: 'Supabase Edge Functions and Auth.'-subtitle: 'Best practices on securing Edge Functions'+description: 'Authentication patterns for Supabase Edge Functions.'+subtitle: 'Authentication patterns for Edge Functions'----<Admonition type="note">--In the past Supabase Auth used a **symmetric** secret to sign legacy JWTs.-But it was replaced by new [JWT Signing Keys](/blog/jwt-signing-keys#start-using-asymmetric-jwts-today). This guide covers the new patterns for securing your Edge Functions.+<Admonition type="caution">-If you need to validate using the old method, read the [Legacy JWT Secret guide](/docs/guides/functions/auth-legacy-jwt).+The patterns in this guide assume your project uses the new [JWT signing keys](/docs/guides/getting-started/api-keys) and the new [API keys](https://github.com/orgs/supabase/discussions/29260). If you're still on legacy JWTs, see the [Legacy JWT Secret guide](/docs/guides/functions/auth-legacy-jwt).</Admonition>-Before continuing, read the [JWT Signing Keys guide](/docs/guides/auth/signing-keys) for details about the main differences compared to Legacy JWTs.+Every request to an Edge Function passes through two layers of auth. First, a platform-level check (`verify_jwt`) runs before your code executes. Then, once the request reaches your handler, you decide what to do with the credentials the caller sent.-## Overview+## Understanding authorization headers-When an HTTP request is sent to Edge Functions, you can use Supabase Auth to secure endpoints. In the past, this verification was controlled by the [`verify_jwt` flag](/docs/guides/functions/function-configuration#skipping-authorization-checks).+Edge Functions care about two request headers. Sending the wrong credential in the wrong header is the most common source of 401 errors.-But, this method is incompatible with the new [JWT Signing Keys](/docs/guides/auth/signing-keys) and also caused trouble when attempting [third-party integration](https://github.com/orgs/supabase/discussions/34988#discussion-8199151).+| Header | Value | Used for |+| --------------- | --------------------------------------- | -------------------------------------- |+| `Authorization` | `Bearer <user-jwt>` | A user signed in through Supabase Auth |+| `apikey` | `sb_publishable_...` or `sb_secret_...` | Calls from clients or services |-For this reason we decided to no longer implicitly force JWT verification, but instead suggest patterns and templates to handle this task. This allows users to own and control the auth code, instead of hiding it internally under Edge Runtime infrastructure.+A common mistake is sending a publishable or secret key as a bearer token: `Authorization: Bearer sb_publishable_...`. The new API keys are not JWTs. The platform check can't validate them, and your handler can't verify them as JWTs either. Instead, put API keys in the `apikey` header.-<Admonition type="caution">+You can send both headers together. A signed-in user calling your function through `supabase-js`, for example, sends their session JWT in `Authorization` and the project's publishable key in `apikey`.-Following the [upcoming API key changes](https://github.com/orgs/supabase/discussions/29260) timetable, the `verify_jwt` flag will still be supported and enabled by default. To move to the new [JWT Signing Keys](/docs/guides/auth/signing-keys), you need to manually [skip the authorization checks](/docs/guides/functions/function-configuration#skipping-authorization-checks) and follow the steps below.+## The `verify_jwt` platform check-</Admonition>+When `verify_jwt` is enabled (the default), the platform inspects the `Authorization` header of every request before your function runs. It expects a valid user JWT. If the header is missing, malformed, or signed with a different key, the platform returns a 401 error, and your code never executes.-## Integrating with Supabase Auth+The check validates legacy HS256 JWTs and JWTs signed with the new asymmetric [signing keys](/docs/guides/auth/signing-keys).-Important notes to consider:+The check does not accept an API key. Publishable and secret keys are not JWTs, so callers that send one in the `Authorization` header fail the check before their request reaches your handler.-- This is done _inside_ the `Deno.serve()` callback argument, so that the Authorization header is set for each request.-- Use `Deno.env.get('SUPABASE_URL')` to get the URL associated with your project. Using a value such as `http://localhost:54321` for local development will fail due to Docker containerization.+Use the `verify_jwt` flag to match how the function is called:-<$Partial path="api_settings.mdx" variables={{ "framework": "", "tab": "" }} />+- **Leave `verify_jwt` on** for functions that are only called with a user JWT, such as functions invoked from the client through `supabase.functions.invoke`. The platform rejects unauthenticated requests before they reach your code, and your handler can trust that a valid JWT is present.+- **Turn `verify_jwt` off** for functions that are called without an `Authorization` header, such as webhooks from external providers, or service-to-service calls that authenticate with an API key. These patterns are covered later in the guide.-<Admonition type="caution">+Set the flag per function in `supabase/config.toml`:-Currently, the new API keys are not available by default on the Edge Functions environment.-But you can manually expose them as [secret](/docs/guides/functions/secrets#local-secrets) using the `SB_` prefix.+```toml+[functions.stripe-webhook]+verify_jwt = false+```-We're working on exposing these secrets and making them default in the future.+For 401 failure modes and how to diagnose them, see [Edge Function 401 error response](/docs/troubleshooting/edge-function-401-error-response).-</Admonition>+## Common auth patterns++The sections below show the four patterns you'll reach for most often, written without an SDK so the auth moves are visible. Business logic is left as a placeholder. The next section shows the same four patterns using [`@supabase/server`](https://github.com/supabase/server).++### Authenticated user calls++Keep `verify_jwt` enabled. The platform validates the JWT before your handler runs. Forward the `Authorization` header to the Supabase client so queries run under the caller's RLS policies.++```toml+[functions.notes]+verify_jwt = true+```++```ts+import { createClient } from 'npm:@supabase/supabase-js@2'++const SUPABASE_PUBLISHABLE_KEYS = JSON.parse(Deno.env.get('SUPABASE_PUBLISHABLE_KEYS')!)++Deno.serve((req) => {+ const supabase = createClient(+ Deno.env.get('SUPABASE_URL')!,+ SUPABASE_PUBLISHABLE_KEYS['default'],+ { global: { headers: { Authorization: req.headers.get('Authorization')! } } }+ )++ // your business logic. queries run as the caller+ return Response.json({ ok: true })+})+```++### Service-to-service calls++Cron jobs, workers, `pg_net`, or another Edge Functions make calls with a secret key on the `apikey` header. These callers don't send a user JWT, so disable `verify_jwt` and validate the key yourself.++```toml+[functions.run-automations]+verify_jwt = false+``````ts-import 'jsr:@supabase/functions-js/edge-runtime.d.ts'import { createClient } from 'npm:@supabase/supabase-js@2'-const supabase = createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SB_PUBLISHABLE_KEY')!)+const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)++Deno.serve((req) => {+ if (req.headers.get('apikey') !== Deno.env.get('INTERNAL_AUTOMATIONS_KEY')) {+ return Response.json({ error: 'forbidden' }, { status: 401 })+ }++ const supabase = createClient(Deno.env.get('SUPABASE_URL')!, SUPABASE_SECRET_KEYS['default'])++ // your business logic. queries run with the service role+ return Response.json({ ok: true })+})+```++<Admonition type="tip">++Never expose a secret key to the browser. Store it as a [function secret](/docs/guides/functions/secrets).++</Admonition>++### Public functions++For a genuinely public function, like a health check, no credential is required. Disable `verify_jwt` so anonymous callers can reach the handler.++```toml+[functions.health]+verify_jwt = false+```++```ts+Deno.serve(() => {+ // your business logic+ return Response.json({ ok: true })+})+```++### External webhooks++External providers like Stripe or GitHub don't send Supabase credentials. They sign the request body with their own shared secret. Disable `verify_jwt` and verify the signature before acting on the payload.++```toml+[functions.stripe-webhook]+verify_jwt = false+```++```ts+import Stripe from 'npm:stripe'++const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)Deno.serve(async (req) => {- const authHeader = req.headers.get('Authorization')!- const token = authHeader.replace('Bearer ', '')-- const { data, error } = await supabase.auth.getClaims(token)- const userEmail = data?.claims?.email- if (!userEmail || error) {- return Response.json(- { msg: 'Invalid JWT' },- {- status: 401,- }- )+ const signature = req.headers.get('stripe-signature') ?? ''+ const body = await req.text()++ try {+ stripe.webhooks.constructEvent(body, signature, Deno.env.get('STRIPE_WEBHOOK_SECRET')!)+ } catch {+ return new Response('bad signature', { status: 400 })}- return Response.json({ message: `hello ${userEmail}` })+ // your business logic. handle the event+ return Response.json({ received: true })})```-## Verifying JWT+## Simplifying with `@supabase/server`++The [`@supabase/server`](https://github.com/supabase/server) package wraps your handler, checks the caller's credentials against a declared `allow` mode, and hands you a pre-configured Supabase client on `ctx`. The same patterns above, written against the SDK, look like this.++| Mode | Accepts |+| ----------------- | ------------------------------------------ |+| `'user'` | A valid user JWT on `Authorization` |+| `'secret:<name>'` | A named secret key on `apikey` |+| `'always'` | Any caller, no check (for signed webhooks) |++<Admonition type="tip">-### Using Supabase template+See the [`@supabase/server` docs](https://github.com/supabase/server) for the full list of modes.-You can see [a custom JWT verification example on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/custom-jwt-validation) and a variety of [auth function templates](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/_shared/jwt) also on GitHub.+</Admonition>++### Authenticated user calls++`allow: 'user'` pairs with `verify_jwt = true`. The platform validates the JWT, and the SDK hands you `ctx.supabase` already scoped to the caller.++```ts+import { withSupabase } from 'npm:@supabase/server'++export default {+ fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {+ // your business logic. ctx.supabase is scoped to the caller+ return Response.json({ email: ctx.userClaims?.email })+ }),+}+```-To verify incoming requests, you can copy/download the specified template and start using it:+### Service-to-service calls++`allow: 'secret:<name>'` validates the `apikey` header against the named secret key from your [dashboard](/dashboard/project/_/settings/api-keys) and gives you `ctx.supabaseAdmin` for privileged work. The `<name>` matches the name you gave the key. Keep `verify_jwt = false`.++```ts+import { withSupabase } from 'npm:@supabase/server'++export default {+ fetch: withSupabase({ allow: 'secret:automations' }, async (_req, ctx) => {+ // your business logic. ctx.supabaseAdmin bypasses RLS+ return Response.json({ ok: true })+ }),+}+```<Admonition type="tip">-The following example uses [`jose`](https://jsr.io/@panva/jose) library to verify received JWTs.+Create a named secret key for each caller in the [**Settings > API keys**](/dashboard/project/_/settings/api-keys) section of the Dashboard. Give it a name like "automations", and share the generated `sb_secret_...` value with the service that calls this function.++++</Admonition>++### Public functions++The SDK adds nothing to a truly public function. Use the raw pattern from the previous section. If you need a Supabase client anyway, `allow: 'always'` with `verify_jwt = false` skips every check and treats every caller as anonymous.++### External webhooks++Use `allow: 'always'` to skip the SDK's credential check, then verify the provider's signature inside the handler. Keep `verify_jwt = false`.++```ts+import { withSupabase } from 'npm:@supabase/server'+import Stripe from 'npm:stripe'++const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)++export default {+ fetch: withSupabase({ allow: 'always' }, async (req, ctx) => {+ const signature = req.headers.get('stripe-signature') ?? ''+ const body = await req.text()++ try {+ stripe.webhooks.constructEvent(body, signature, Deno.env.get('STRIPE_WEBHOOK_SECRET')!)+ } catch {+ return new Response('bad signature', { status: 400 })+ }++ // your business logic. ctx.supabaseAdmin available for db work+ return Response.json({ received: true })+ }),+}+```++<Admonition type="caution">++`allow: 'always'` disables every credential check. Your handler is fully responsible for authenticating the caller. Never use it on an endpoint that reads or writes sensitive data without verifying the caller some other way.++</Admonition>++### Combining modes++Functions that answer both users and internal callers take an array on `allow`. Modes are tried in order. The first match wins, and `ctx.authType` tells you which matched.++```ts+import { withSupabase } from 'npm:@supabase/server'++export default {+ fetch: withSupabase({ allow: ['user', 'secret:automations'] }, async (req, ctx) => {+ if (ctx.authType === 'user') {+ // your business logic for user calls. ctx.supabase is scoped to them+ return Response.json({ ok: true })+ }++ // your business logic for service calls. ctx.supabaseAdmin bypasses RLS+ return Response.json({ ok: true })+ }),+}+```++### Custom error responses++To shape the 401 response yourself, use `createSupabaseContext` instead of `withSupabase`. It returns a `{ data, error }` tuple so you stay in control.++```ts+import { createSupabaseContext } from 'npm:@supabase/server'++export default {+ fetch: async (req: Request) => {+ const { data: ctx, error } = await createSupabaseContext(req, { allow: 'user' })+ if (error) {+ return Response.json({ message: error.message, code: error.code }, { status: error.status })+ }+ return Response.json({ message: `hello ${ctx.userClaims?.email}` })+ },+}+```++## Environment variables++`@supabase/server` reads its configuration from a standard set of environment variables. On the Supabase platform and in local development with the CLI, these are auto-provisioned.++| Variable | What it is |+| --------------------------- | ----------------------------------------- |+| `SUPABASE_URL` | Your project URL |+| `SUPABASE_PUBLISHABLE_KEYS` | Named publishable keys as a JSON object |+| `SUPABASE_SECRET_KEYS` | Named secret keys as a JSON object |+| `SUPABASE_JWKS` | JSON Web Key Set used to verify user JWTs |++Local development with the CLI uses a single-key setup, which the SDK also accepts as a fallback: `SUPABASE_PUBLISHABLE_KEY` and `SUPABASE_SECRET_KEY`.++<Admonition type="note">++The same zero-config experience is available on other runtimes. Install [`@supabase/server`](https://github.com/supabase/server) in your Node.js, Bun, Cloudflare Workers, or self-hosted Deno app and set the environment variables above. See the package's [environment variables guide](https://github.com/supabase/server/blob/main/docs/environment-variables.md) for the full reference.</Admonition>-{/* prettier-ignore */}-<$CodeSample-path="/edge-functions/supabase/functions/_shared/jwt/default.ts"-meta="name=_shared/jwt/default.ts"-lines={[[3, -1]]}-/>--<$CodeSample-path="/edge-functions/supabase/functions/custom-jwt-validation/index.ts"-meta="name=hello/index.ts"-lines={[[4, -1]]}-/>diff --git a/apps/docs/public/img/guides/functions/secret-keys-automations.png b/apps/docs/public/img/guides/functions/secret-keys-automations.pngnew file mode 100644index 00000000000..edc87354151Binary files /dev/null and b/apps/docs/public/img/guides/functions/secret-keys-automations.png differ