# Supabase

Protect routes with Supabase-issued tokens when your app already uses Supabase Auth as the identity provider. The gateway validates Supabase JWTs using the project JWT secret, checking issuer and audience claims. Use this when you want edge-level auth without running Supabase client libraries in your backend.

**Last reviewed:** 2026-03-06

## When to use this

Use the Supabase integration guides when your application uses Supabase Auth for identity and you want passwordless (OTP) authentication flows managed at the gateway edge. The gateway handles sending OTP codes and verifying them, so your backend only sees authenticated requests.

## Key concepts

* The Supabase authorizer validates JWTs issued by Supabase Auth using the project's JWT secret. Configure `jwt_secret`, `issuer`, and `audience` in the authorizer block.
* The `supabase_passwordless_auth` integration sends OTP codes via email or phone through Supabase's GoTrue API. The gateway constructs the request from the client payload and Supabase environment variables.
* The `supabase_passwordless_verify` integration verifies OTP codes and returns Supabase session tokens. The client sends the OTP code and the gateway validates it against Supabase.
* Supabase requires specific environment variables: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, and `SUPABASE_JWT_SECRET`. All three must be set before any Supabase integration works.
* If Supabase is configured to send magic links instead of numeric OTP codes, the verify flow will not work. This is controlled in the Supabase dashboard under Auth settings.

## Repo-grounded example

```json
{
  "authorizer": {
    "type": "supabase",
    "jwt_secret": "$env.SUPABASE_JWT_SECRET",
    "issuer": "https://project.supabase.co/auth/v1",
    "audience": "authenticated"
  },
  "paths": [
    {
      "method": "POST",
      "path": "/api/v1/supabase/auth",
      "integration": { "type": "supabase_passwordless_auth" }
    },
    {
      "method": "POST",
      "path": "/api/v1/supabase/verify",
      "integration": { "type": "supabase_passwordless_verify" }
    }
  ]
}
```

This snippet configures the Supabase authorizer with `jwt_secret`, `issuer`, and `audience`. Any path with `auth: true` will require a valid Supabase-issued JWT in the Authorization header. The gateway checks the token signature, expiry, issuer, and audience before forwarding the request.

## Troubleshooting

* If OTP sending fails with a 400 error, verify that `SUPABASE_URL` and `SUPABASE_ANON_KEY` are set correctly and that the Supabase project has email or phone auth enabled.
* If OTP verification returns "invalid token", confirm that Supabase is configured to send numeric OTP codes, not magic links -- check the Auth settings in your Supabase dashboard.
* If JWT validation fails on protected routes, confirm that `SUPABASE_JWT_SECRET` matches the JWT secret shown in your Supabase project settings (Settings > API > JWT Secret).
* If you receive a "missing email or phone" error, ensure the client request body includes either an `email` or `phone` field in the JSON payload sent to the auth endpoint.

## Related docs

* [supabase otp](/configuration/supabase-otp.md)
* [authorizer](/configuration/authorizer.md)
* [gateway troubleshooting matrix](/troubleshooting/wrangler-deploy-guide/gateway-troubleshooting-matrix.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/integrations/supabase-jwt-protected-routes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.