Securing Edge Functions

Secure an Edge Function by declaring which credentials it accepts. The withSupabase wrapper from the @supabase/server package on GitHub checks each caller against the auth mode you set. Your handler receives a preconfigured Supabase client on ctx.

• Choose an auth mode compares the four modes. Start here if you aren't sure which one your function needs.
• Secure your function has an example for each mode, plus how to combine modes and shape your own error response.
• Environment variables lists what @supabase/server reads from the environment.

Choose an auth mode

Each mode names the credential a caller must present. withSupabase accepts four:

For how authorization headers and the verify_jwt platform check work, see Authorization headers.

Secure your function

Each of the following sections covers one mode, then how to combine modes and shape your own error response. Every example wraps the handler in withSupabase and reads its Supabase client from ctx.

Authenticated user calls

When a signed-in user calls a function, the request carries the user's session JWT on the Authorization header. Your app usually makes that call through supabase.functions.invoke. Use auth: 'user' to get a ctx.supabase scoped to the caller's Row Level Security (RLS) policies.

The default is verify_jwt = true, so the platform validates the JWT before your handler runs. Leave it on for user-facing functions. Turning it off to clear a 401 during development removes the platform's check, leaving withSupabase as the only thing that verifies the caller.

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    const { supabase, supabaseAdmin, userClaims, jwtClaims, authMode } = ctx
    // supabase       — RLS-scoped to the authenticated user
    // supabaseAdmin  — bypasses RLS (service role)
    // userClaims     — user identity from JWT (id, email, role)
    // jwtClaims      — full JWT claims
    // authMode       — which auth mode matched

    // your business logic goes here
    return Response.json({ email: ctx.userClaims?.email })
  }),
}

Reach for ctx.supabase when the handler serves the signed-in caller. It applies their RLS policies to every query. Use ctx.supabaseAdmin only for work that has to cross those policies.

Service-to-service calls

Cron jobs, workers, pg_net, and other Edge Functions make calls with a secret key on the apikey header rather than a user JWT. To accept the key:

1. In supabase/config.toml, disable the verify_jwt check for the function:

   [functions.your-function]
   verify_jwt = false

2. In the function, use auth: 'secret'. The wrapper validates the key against the secret key named default in your project's API keys, and gives your handler ctx.supabaseAdmin for privileged work:

   import { withSupabase } from 'npm:@supabase/server@1'
   
   export default {
     fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
       // your business logic. ctx.supabaseAdmin bypasses RLS
       return Response.json({ ok: true })
     }),
   }

To call a function from Postgres with the secret key, see Call an Edge Function for Database Webhooks and Scheduling Edge Functions for pg_cron.

Public functions

For a genuinely public function, such as a health check, use auth: 'none' with verify_jwt = false so anonymous callers can reach the handler.

[functions.health]
verify_jwt = false

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'none' }, async () => {
    // your business logic
    return Response.json({ ok: true })
  }),
}

auth: 'none' accepts every caller. For a function that authenticates callers itself, see the External webhooks section of this page.

External webhooks

External providers such as Stripe or GitHub don't send Supabase credentials. They sign the request body with their own shared secret. Use auth: 'none' to skip the wrapper's credential check, then verify the provider's signature inside the handler. Keep verify_jwt = false.

import { withSupabase } from 'npm:@supabase/server@1'
import Stripe from 'npm:stripe'

const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)

// Deno has no synchronous Node crypto, so signature verification must go through
// Stripe's SubtleCryptoProvider. The synchronous `constructEvent()` throws
// "SubtleCryptoProvider cannot be used in a synchronous context" on this runtime.
const cryptoProvider = Stripe.createSubtleCryptoProvider()

export default {
  fetch: withSupabase({ auth: 'none' }, async (req, ctx) => {
    const signature = req.headers.get('stripe-signature') ?? ''
    const body = await req.text()

    try {
      await stripe.webhooks.constructEventAsync(
        body,
        signature,
        Deno.env.get('STRIPE_WEBHOOK_SECRET')!,
        undefined,
        cryptoProvider
      )
    } catch (err) {
      // Log the reason so a configuration error isn't mistaken for a forged payload.
      console.error('Stripe signature verification failed:', err)
      return new Response('bad signature', { status: 400 })
    }

    // your business logic. ctx.supabaseAdmin available for database work
    return Response.json({ received: true })
  }),
}

Combining modes

Functions that answer both users and internal callers take an array on auth. The wrapper tries each mode in order and uses the first one that matches. ctx.authMode tells you which mode matched.

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: ['user', 'secret'] }, async (req, ctx) => {
    if (ctx.authMode === '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 instead of rejecting the request for you.

import { createSupabaseContext } from 'npm:@supabase/server@1'

export default {
  fetch: async (req: Request) => {
    const { data: ctx, error } = await createSupabaseContext(req, { auth: '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, which the Supabase Platform and the Supabase CLI provision for you.

Local development with the CLI uses a single-key setup. @supabase/server also accepts SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY as a fallback.