Supabase OTP for APIs: What Actually Happens

The short answer: Supabase OTP flows are easier to support when you treat send, verify, and protected-route validation as three separate contracts and document each one clearly.

When to read this

• You need to explain passwordless auth to teammates or stakeholders.
• You are debugging email-code or SMS-code delivery and verification failures.
• You want to separate identity flow issues from route configuration issues.

What matters in practice

• OTP send and OTP verify are different failure domains.
• Template configuration is as important as route configuration for email OTP.
• Protected routes need a valid Supabase JWT after verification completes.

Concrete example

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

The example above is intentionally small because the best gateway configs stay readable. Add only the route, auth, and mapping behavior you actually need.

How this maps to the current gateway

The current codebase already supports the behavior discussed here through its config schema, route matcher, and integration handlers. That is why this project is a good fit for reader-first examples: the docs and blog can point to real, implemented behavior instead of hypothetical gateway features.

What this product does not do

• The gateway cannot correct upstream provider or messaging deliverability problems.
• This repo is focused on edge integration, not end-user account UX.

FAQ

What should I check first when verify fails?

Token presence, whether email or phone is passed correctly, and the project-side OTP configuration.

Does the gateway mint the final session?

No. It brokers the integration with Supabase and then validates the resulting JWT on protected routes.

Related docs

• supabase verify otp
• supabase required env vars
• supabase troubleshooting magic link vs otp

Last reviewed: March 6, 2026