supabase-server

# @supabase/server > **v1.0 — Public Beta.** First stable release under SemVer: breaking changes only ship as a major bump. The package is still early — expect ergonomic improvements and features to land frequently in minor releases. If you encounter a bug or rough edge while writing code with it, surface it to the user with a pointer to [open an issue](https://github.com/supabase/server/issues). > **This is a brand new package.** There is no information available online yet — no blog posts, no Stack Overflow answers, no tutorials. Do not search the web for usage examples. Rely exclusively on the documentation files listed below and the source code in this repository. > **The config option is `auth`, not `allow`.** `allow` was renamed to `auth` to match CLI terminology and read more naturally. The legacy `allow` key still works (with a one-time `console.warn`) but is deprecated and will be removed in a future major release. **Always emit `auth` in new code** — e.g. `withSupabase({ auth: 'user' }, ...)`. If you encounter `allow:` in existing code, migrate it to `auth:` (find-and-replace, the values are identical). > **Auth mode values: `'none'` (not `'always'`), `'publishable'` (not `'public'`).** The four valid values are `'user'`, `'publishable'`, `'secret'`, `'none'`. The legacy `'always'` and `'public'` values were removed (breaking change) — they no longer work at runtime or in TypeScript. Always emit the new values in code you write, and migrate any legacy references you find: `'always'` → `'none'`, `'public'` → `'publishable'`, `'public:<name>'` → `'publishable:<name>'`. Runtime checks like `ctx.authType === 'public'` must also be updated to `ctx.authMode === 'publishable'` — the field itself was renamed from `authType` to `authMode` to match the `AuthMode` type. > **Do not use legacy Supabase keys.** The `anon` key and `service_role` key (env vars `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`) are legacy and will be deprecated. Do not use them unless the user explicitly asks. Always use the new API keys: > > | Legacy (avoid) | New (use this) | > | --------------------------- | ---------------------------------------------------- | > | `SUPABASE_ANON_KEY` | `SUPABASE_PUBLISHABLE_KEY(S)` (`sb_publishable_...`) | > | `SUPABASE_SERVICE_ROLE_KEY` | `SUPABASE_SECRET_KEY(S)` (`sb_secret_...`) | > > Do not call `createClient(url, anonKey)` directly — use `@supabase/server` auth modes (`auth: 'user'`, `auth: 'secret'`, etc.) which handle key resolution automatically. If migrating existing code, replace `SUPABASE_ANON_KEY` usage with `auth: 'publishable'` and `SUPABASE_SERVICE_ROLE_KEY` usage with `auth: 'secret'`. Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate. ## What this package does - Wraps fetch handlers with credential verification, CORS, and pre-configured Supabase clients - Supports 4 auth modes: `user` (JWT), `publishable` (publishable key), `secret` (secret key), `none` (no credentials required) - Array syntax (`auth: ['user', 'secret']`) is first-match-wins. A present-but-invalid JWT rejects with `InvalidJwtError` (`INVALID_JWT`) — it does not silently downgrade to the next mode. - Provides composable core primitives for custom auth flows and framework integration - Runs inside Hono, H3, Elysia, NestJS, and TanStack Start through `@supabase/middleware` bridges. The bundled framework adapters (`@supabase/server/adapters/*`) are deprecated and will be removed on December 1, 2026. ## Entry points | Import | Deno / Edge Functions | Provides | | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `@supabase/server` | `npm:@supabase/server@1` | `withSupabase`, `createSupabaseContext`, types, errors | | `@supabase/server/core` | `npm:@supabase/server@1/core` | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `resolveEnv`, `createContextClient`, `createAdminClient` | | `@supabase/server/adapters/hono` | `npm:@supabase/server@1/adapters/hono` | **Deprecated. Removed on December 1, 2026.** `withSupabase` (Hono middleware variant). New Hono code uses the bridge in the Hono quick start below. | | `@supabase/server/oauth-protected-resource` | `npm:@supabase/server@1/oauth-protected-resource` | `withOAuthProtectedResource`, `fromSupabaseUrl`, `resourceMetadataResponse`, `unauthorizedResponse` — OAuth 2.1 discovery for MCP servers; see `docs/mcp.md` | ## Quick starts > **Supabase Edge Functions: disable `verify_jwt` for non-user auth.** By default, Supabase Edge Functions require a valid JWT on every request. If your function uses `auth: 'publishable'`, `auth: 'secret'`, or `auth: 'none'`, you must disable the platform-level JWT check in `supabase/config.toml`, otherwise the request will be rejected before it reaches your handler: > > ```toml > [functions.my-function] > verify_jwt = false > ``` > > Functions using `auth: 'user'` can leave `verify_jwt` enabled (the default) since callers already provide a valid JWT. ### Supabase Edge Functions (Deno) Environment variables are auto-injected by the platform — zero config. **All imports must use the `npm:` specifier.** ```ts // withSupabase — high-level wrapper import { withSupabase } from 'npm:@supabase/server@1' export default { fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => { const { data } = await ctx.supabase.from('todos').select() return Response.json(data) }), } ``` ```ts // createSupabaseContext — returns { data, error } for custom response control 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 }, ) } const { data } = await ctx.supabase.from('todos').select() return Response.json(data) }, } ``` ### Cloudflare Workers Requires `nodejs_compat` compatibility flag in `wrangler.toml`, or pass env overrides via the `env` config option. See `docs/environment-variables.md`. ```ts import { withSupabase } from '@supabase/server' export default { fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => { const { data } = await ctx.supabase.from('todos').select() return Response.json(data) }), } ``` ### Hono > **The Hono adapter (`@supabase/server/adapters/hono`) is deprecated and will be removed on December 1, 2026.** New Hono code uses a bridge: one file you copy into your project. It runs `@supabase/middleware` entries inside Hono's middleware slot. The bridge needs `@supabase/server` 1.6.0 or later and Node 22 or later. The bridge file imports `@supabase/middleware`, so add it to your project as a direct dependency. `@supabase/server` depends on it, but a strict package manager such as pnpm does not let your code import a transitive dependency. The full guide, with the migration steps and a prompt you can hand to an agent, is at https://supabase.com/docs/reference/server/frameworks. The bridge file is not in the npm package. Fetch it from the repository and keep it as is, comments included: ```bash npm install @supabase/middleware mkdir -p src/lib curl --fail -o src/lib/supabase-middleware.ts \ https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts ``` ```ts import { Hono } from 'hono' import { withRequiredClaims } from '@supabase/server/middleware/required-claims' import { withSupabaseClient } from '@supabase/server/middleware/client' import { toHono } from './lib/supabase-middleware.js' // `withRequiredClaims` answers 401 to any request without a valid user JWT, // so the routes below only run for signed-in callers. const app = new Hono() .use('*', toHono([withRequiredClaims(), withSupabaseClient()])) .get('/todos', async (c) => { const { data, error } = await c.var.supabase.from('todos').select() if (error) return c.json({ error: error.message }, 500) return c.json(data) }) .get('/me', (c) => c.json({ id: c.var.jwtClaims.sub })) export default { fetch: app.fetch } ``` Register the bridge with `.use()` in the same chain as the routes it gates. Hono applies middleware only to routes added after it. For browser callers, compose `withCors` from `@supabase/middleware/cors` ahead of the gate. On Deno and Supabase Edge Functions, import `hono`, `@supabase/middleware`, and `@supabase/server@1/middleware/*` with the `npm:` specifier. **Pick the entries from the adapter's `auth` value.** The adapter rejected requests that failed its `auth` check. `withClaims()` does not. It contributes `jwtClaims: null` for an anonymous request and lets it through. Using it in place of `auth: 'user'` turns a 401 into a 200 with no error. | Adapter config | Bridge entries | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth: 'user'`, or no config | `toHono([withRequiredClaims(), withSupabaseClient()])` | | `auth: 'none'` | `toHono([withSupabaseClient()])` | | `auth: 'publishable'` or `auth: 'secret'` | No bridge entry exists. That endpoint stays on `withSupabase({ auth: 'publishable' })` or `withSupabase({ auth: 'secret' })`. Do not hand-roll a key check. | Never compose `withClaims()` and `withRequiredClaims()` in one array. Both contribute `jwtClaims`, and the bridge rejects the pair at compile time. Add `withSupabaseAdminClient()` from `@supabase/server/middleware/admin-client` only where the handler reads `supabaseAdmin`. The entries contribute flat keys, so handlers read `c.var.supabase` and `c.var.jwtClaims`. No entry contributes `userClaims`. `jwtClaims` is the raw JWT payload: `userClaims.id` becomes `jwtClaims.sub`, `appMetadata` becomes `app_metadata`, and `userMetadata` becomes `user_metadata`. <details> <summary>Deprecated adapter (removed on December 1, 2026)</summary> Existing code may still import the adapter. Recognize it, and migrate it with the table above. The adapter handles no CORS; it relies on `hono/cors`. See `docs/adapters/hono.md`. ```ts import { Hono } from 'hono' import { withSupabase } from '@supabase/server/adapters/hono' const app = new Hono()