Getting Started with OAuth 2.1 Server

1. Go to your project dashboard
2. Navigate to Authentication > OAuth Server in the sidebar
3. Enable OAuth 2.1 server capabilities

Edit your supabase/config.toml file and add the OAuth server configuration:

[auth.oauth_server]
enabled = true
authorization_url_path = "/oauth/consent"
allow_dynamic_registration = false  # Optional: enable dynamic client registration

Start or restart your local Zuvo instance:

supabase start
# or if already running:
supabase stop && supabase start

Expose local instance to the world

To test OAuth flows with external applications, you can expose your local Zuvo instance using a tunnel solution (such as ngrok or Cloudflare Tunnel).

When using a tunnel, configure the jwt_issuer field in your supabase/config.toml to match your tunnel URL:

[auth]
jwt_issuer = "https://my-tunnel.url/auth/v1"

This ensures that JWTs issued by your local instance use the correct issuer claim for token validation, and serves the discovery endpoint at the correct location with accurate discovery information.

The Zuvo Auth SDK contains three different functions for authenticating user access to applications:

Summary of the methods

• Use getClaims to protect pages and user data. It reads the access token from storage and verifies it. Locally via the WebCrypto API and a cached JWKS endpoint when the project uses asymmetric signing keys (the default for new projects), or by calling getUser solely to validate when symmetric keys are in use. The returned claims always come from decoding the JWT, not from a user lookup.
• getUser makes a network call to the project's Auth instance to get the user record, which includes the most up-to-date information about the user at the cost of a network call.
• getSession when you need the raw session (the access token, refresh token, and expiry). For example to forward the access token to another service. The session is loaded directly from local storage and isn't re-validated against the Auth server, so the embedded user object shouldn't be trusted on its own when storage is shared with the client (cookies, request headers). To verify identity, validate the access token with getClaims, or call getUser for a fresh, server-confirmed user record.

In summary: use getClaims to verify identity (typically for protecting pages and data), getUser when you need an up-to-date user record from the Auth server, and getSession when you need the access or refresh token directly, but don't rely on the user object it returns for authorization decisions.

// app/oauth/consent/page.tsx
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'

export default async function ConsentPage({
  searchParams,
}: {
  searchParams: { authorization_id?: string }
}) {
  const authorizationId = (await searchParams).authorization_id

  if (!authorizationId) {
    return <div>Error: Missing authorization_id</div>
  }

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll: async () => (await cookies()).getAll(),
        setAll: async (cookiesToSet, _headers) => {
          const cookieStore = await cookies()
          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
        },
      },
    }
  )

  // Check if user is authenticated
  const { data } = await supabase.auth.getClaims()
  const claims = data?.claims

  if (!claims) {
    // Redirect to login, preserving authorization_id
    redirect(`/login?redirect=/oauth/consent?authorization_id=${authorizationId}`)
  }

  // Get authorization details using the authorization_id
  const { data: authDetails, error } =
    await supabase.auth.oauth.getAuthorizationDetails(authorizationId)

  if (error || !authDetails) {
    return <div>Error: {error?.message || 'Invalid authorization request'}</div>
  }

  // if no authorization_id returned, user has previously consented, redirect them
  if (!('authorization_id' in authDetails)) {
    redirect(authDetails['redirect_url'])
  }

  return (
    <div>
      <h1>Authorize {authDetails.client.name}</h1>
      <p>This application wants to access your account.</p>

      <div>
        <p>
          <strong>Client:</strong> {authDetails.client.name}
        </p>
        <p>
          <strong>Redirect URI:</strong> {authDetails.redirect_uri}
        </p>
        {authDetails.scope && authDetails.scope.trim() && (
          <div>
            <strong>Requested permissions:</strong>
            <ul>
              {authDetails.scope.split(' ').map((scopeItem) => (
                <li key={scopeItem}>{scopeItem}</li>
            </ul>
          </div>
      </div>

      <form action="/api/oauth/decision" method="POST">
        <input type="hidden" name="authorization_id" value={authorizationId} />
        <button type="submit" name="decision" value="approve">
          Approve
        </button>
        <button type="submit" name="decision" value="deny">
          Deny
        </button>
      </form>
    </div>
  )
}

// app/api/oauth/decision/route.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const formData = await request.formData()
  const decision = formData.get('decision')
  const authorizationId = formData.get('authorization_id') as string

  if (!authorizationId) {
    return NextResponse.json({ error: 'Missing authorization_id' }, { status: 400 })
  }

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll: async () => (await cookies()).getAll(),
        setAll: async (cookiesToSet, _headers) => {
          const cookieStore = await cookies()
          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
        },
      },
    }
  )

  if (decision === 'approve') {
    const { data, error } = await supabase.auth.oauth.approveAuthorization(authorizationId)

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 400 })
    }

    // Redirect back to the client with authorization code
    return NextResponse.redirect(data.redirect_url)
  } else {
    const { data, error } = await supabase.auth.oauth.denyAuthorization(authorizationId)

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 400 })
    }

    // Redirect back to the client with error
    return NextResponse.redirect(data.redirect_url)
  }
}

// src/pages/OAuthConsent.tsx
import { useEffect, useState } from 'react'
import { useNavigate, useSearchParams } from 'react-router-dom'

import { supabase } from './supabaseClient'

export function OAuthConsent() {
  const navigate = useNavigate()
  const [searchParams] = useSearchParams()
  const authorizationId = searchParams.get('authorization_id')

  const [authDetails, setAuthDetails] = useState<any>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function loadAuthDetails() {
      if (!authorizationId) {
        setError('Missing authorization_id')
        setLoading(false)
        return
      }

      // Check if user is authenticated
      const {
        data: { user },
      } = await supabase.auth.getUser()

      if (!user) {
        navigate(`/login?redirect=/oauth/consent?authorization_id=${authorizationId}`)
        return
      }

      // Get authorization details using the authorization_id
      const { data, error } = await supabase.auth.oauth.getAuthorizationDetails(authorizationId)

      if (error) {
        setError(error.message)
      } else {
        setAuthDetails(data)
      }

      setLoading(false)
    }

    loadAuthDetails()
  }, [authorizationId, navigate])

  async function handleApprove() {
    if (!authorizationId) return

    const { data, error } = await supabase.auth.oauth.approveAuthorization(authorizationId)

    if (error) {
      setError(error.message)
    } else {
      // Redirect to client app
      window.location.href = data.redirect_url
    }
  }

  async function handleDeny() {
    if (!authorizationId) return

    const { data, error } = await supabase.auth.oauth.denyAuthorization(authorizationId)

    if (error) {
      setError(error.message)
    } else {
      // Redirect to client app with error
      window.location.href = data.redirect_url
    }
  }

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error}</div>
  if (!authDetails) return <div>No authorization request found</div>

  return (
    <div>
      <h1>Authorize {authDetails.client.name}</h1>
      <p>This application wants to access your account.</p>

      <div>
        <p>
          <strong>Client:</strong> {authDetails.client.name}
        </p>
        <p>
          <strong>Redirect URI:</strong> {authDetails.redirect_uri}
        </p>
        {authDetails.scope && authDetails.scope.trim() && (
          <div>
            <strong>Requested permissions:</strong>
            <ul>
              {authDetails.scope.split(' ').map((scopeItem) => (
                <li key={scopeItem}>{scopeItem}</li>
            </ul>
          </div>
      </div>

      <div>
        <button onClick={handleApprove}>Approve</button>
        <button onClick={handleDeny}>Deny</button>
      </div>
    </div>
  )
}

1. Go to Authentication > OAuth Apps (under the Manage section)
2. Click Add a new client
3. Enter the client details:
   • Client name: A friendly name for your application
   • Redirect URIs: One or more URLs where users will be redirected after authorization
   • Client type: Choose between:
     • Public - For mobile and single-page apps (no client secret)
     • Confidential - For server-side apps (includes client secret)
4. Click Create

You'll receive:

• Client ID: A unique identifier for the client
• Client Secret (for confidential clients): A secret key for authenticating the client

Token endpoint authentication method

When a client exchanges an authorization code or refreshes a token, it must authenticate with the token endpoint. The token_endpoint_auth_method controls how this authentication happens:

Defaults: Public clients default to none. Confidential clients default to client_secret_basic (per RFC 7591).

Constraints: Public clients must use none. Confidential clients cannot use none.

You can set this when registering a client via the dashboard or programmatically. See OAuth Flows for examples of each method in action.

You can register clients programmatically using the SDK admin endpoints or by calling your project's auth server admin endpoint directly.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://your-project-id.supabase.co',
  'sb_secret_...' // Use the secret key for admin operations
)

// Create an OAuth client
const { data, error } = await supabase.auth.admin.oauth.createClient({
  name: 'My Third-Party App',
  redirect_uris: ['https://my-app.com/auth/callback', 'https://my-app.com/auth/silent-callback'],
  client_type: 'confidential',
  // Optional: defaults to 'client_secret_basic' for confidential, 'none' for public
  token_endpoint_auth_method: 'client_secret_basic',
})

if (error) {
  console.error('Error creating client:', error)
} else {
  console.log('Client created:', data)
  console.log('Client ID:', data.client_id)
  console.log('Client Secret:', data.client_secret) // Store this securely!
}

curl -X POST 'https://<project-ref>.supabase.co/auth/v1/admin/oauth/clients' \
  -H "Authorization: Bearer ${SUPABASE_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Third-Party App",
    "redirect_uris": [
      "https://my-app.com/auth/callback",
      "https://my-app.com/auth/silent-callback"
    ],
    "client_type": "confidential",
    "token_endpoint_auth_method": "client_secret_basic"
  }'

curl -X POST 'http://localhost:54321/auth/v1/admin/oauth/clients' \
  -H "Authorization: Bearer ${SUPABASE_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local Dev App",
    "redirect_uris": ["http://localhost:3000/auth/callback"],
    "client_type": "confidential",
    "token_endpoint_auth_method": "client_secret_post"
  }'

{
  "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "client_secret": "verysecret-1234567890abcdef...",
  "name": "My Third-Party App",
  "redirect_uris": ["https://my-app.com/auth/callback", "https://my-app.com/auth/silent-callback"],
  "client_type": "confidential",
  "token_endpoint_auth_method": "client_secret_basic",
  "created_at": "2025-01-15T10:30:00.000Z"
}

List OAuth clients

To view all registered OAuth clients:

const { data, error } = await supabase.auth.admin.oauth.listClients()

if (error) {
  console.error('Error listing clients:', error)
} else {
  console.log('OAuth clients:', data)
}

curl 'https://<project-ref>.supabase.co/auth/v1/admin/oauth/clients' \
  -H "Authorization: Bearer ${SUPABASE_SECRET_KEY}"

curl 'http://localhost:54321/auth/v1/admin/oauth/clients' \
  -H "Authorization: Bearer ${SUPABASE_SECRET_KEY}"