Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs/functions auth structure (#50885)

Miranda Limonczenko259dbe11f1dc
diff --git a/apps/docs/content/guides/functions/auth.mdx b/apps/docs/content/guides/functions/auth.mdx
index 511dfe9ce9a..4ab0d76a578 100644
--- a/apps/docs/content/guides/functions/auth.mdx
+++ b/apps/docs/content/guides/functions/auth.mdx
@@ -7,9 +7,13 @@ subtitle: 'Authentication patterns for Edge Functions'
Secure an Edge Function by declaring which credentials it accepts. The `withSupabase` wrapper from the [`@supabase/server` package](https://github.com/supabase/server) on GitHub checks each caller against the `auth` mode you set. Your handler receives a preconfigured Supabase client on `ctx`.
-For how authorization headers and the `verify_jwt` platform check work, see [Authorization headers](/docs/guides/functions/auth-headers).
+- [Choose an auth mode](#choose-an-auth-mode) compares the four modes. Start here if you aren't sure which one your function needs.
+- [Secure your function](#secure-your-function) has an example for each mode, plus how to combine modes and shape your own error response.
+- [Environment variables](#environment-variables) lists what `@supabase/server` reads from the environment.
+
+## Choose an auth mode
-The wrapper accepts four `auth` modes:
+Each mode names the credential a caller must present. `withSupabase` accepts four:
| Mode | Accepts |
| --------------- | ------------------------------------------ |
@@ -18,7 +22,13 @@ The wrapper accepts four `auth` modes:
| `'publishable'` | A publishable key on `apikey` |
| `'none'` | Any caller, no check (for signed webhooks) |
-## Authenticated user calls
+For how authorization headers and the `verify_jwt` platform check work, see [Authorization headers](/docs/guides/functions/auth-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`. The default is `verify_jwt = true`. The platform validates the JWT before your handler runs. Use `auth: 'user'` to get a `ctx.supabase` scoped to the caller's Row Level Security (RLS) policies.
@@ -40,7 +50,7 @@ export default {
}
```
-## Service-to-service calls
+### 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. Disable `verify_jwt` and use `auth: 'secret'`. The wrapper validates the key against any secret key in your [project's API keys](/dashboard/project/_/settings/api-keys), and gives your handler `ctx.supabaseAdmin` for privileged work.
@@ -63,7 +73,7 @@ To accept only one specific key, use `auth: 'secret:<name>'`. For example, `auth
</Admonition>
-## Public functions
+### 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.
@@ -85,7 +95,7 @@ export default {
`auth: 'none'` accepts every caller. For a function that authenticates callers itself, see the [External webhooks](#external-webhooks) section of this page.
-## External webhooks
+### 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`.
@@ -131,7 +141,7 @@ export default {
</Admonition>
-## Combining modes
+### 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.
@@ -151,7 +161,7 @@ export default {
}
```
-## Custom error responses
+### 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.
diff --git a/apps/docs/data/content-listings/functions.data.ts b/apps/docs/data/content-listings/functions.data.ts
index bb69d870704..7400312387c 100644
--- a/apps/docs/data/content-listings/functions.data.ts
+++ b/apps/docs/data/content-listings/functions.data.ts
@@ -21,9 +21,9 @@ export const functionsExamplesSupabase: ContentListingGroup = {
type: 'grid',
items: [
{
- title: 'With supabase-js',
+ title: 'Securing Edge Functions',
href: '/guides/functions/auth',
- description: 'Use the Supabase client inside your Edge Function.',
+ description: 'Declare which credentials your Edge Function accepts.',
},
{
title: 'Connect to Postgres',