Getting Started with OAuth 2.1 Server

This guide will walk you through setting up your Supabase project as an OAuth 2.1 identity provider, from enabling the feature to registering your first client application.

Prerequisites#

Before you begin, make sure you have:

• A Supabase project (create one at supabase.com)
• Admin access to your project
• (Optional) Supabase CLI v2.54.11 or higher for local development

Overview#

Setting up OAuth 2.1 in your Supabase project involves these steps:

1. Enable OAuth 2.1 server capabilities in your project
2. Configure your authorization path
3. Build your authorization UI (frontend)
4. Register OAuth client applications

Enable OAuth 2.1 server#

OAuth 2.1 server is currently in beta and free to use during the beta period on all Supabase plans.

Once enabled, your project will expose the necessary OAuth endpoints:

Configure your authorization path#

Before registering clients, you need to configure where your authorization UI will live.

1. In your project dashboard, navigate to Authentication > OAuth Server
2. Set the Authorization Path (e.g., /oauth/consent)

Your authorization UI will be at the combined Site URL + Authorization Path. For example:

• Site URL: https://example.com (from Authentication > URL Configuration)
• Authorization Path: /oauth/consent (from OAuth Server settings)
• Your authorization UI: https://example.com/oauth/consent

When OAuth clients initiate the authorization flow, Supabase Auth will redirect users to this URL with an authorization_id query parameter. You'll use Supabase JavaScript library OAuth methods to handle the authorization:

• supabase.auth.oauth.getAuthorizationDetails(authorization_id) - Retrieve client and authorization details
• supabase.auth.oauth.approveAuthorization(authorization_id) - Approve the authorization request
• supabase.auth.oauth.denyAuthorization(authorization_id) - Deny the authorization request

Build your authorization UI#

This is where you build the frontend for your authorization flow. When third-party apps initiate OAuth, users will be redirected to your authorization path (configured in the previous step) with an authorization_id query parameter.

Your authorization UI should:

1. Extract authorization_id - Get the authorization_id from the URL query parameters
2. Authenticate the user - If not already logged in, redirect to your login page (preserving the authorization_id)
3. Retrieve authorization details - Use supabase.auth.oauth.getAuthorizationDetails(authorization_id) to get client information including requested scopes
4. Display consent screen - Show the user what app is requesting access and what scopes/permissions are being requested
5. Handle user decision - Call either approveAuthorization(authorization_id) or denyAuthorization(authorization_id) based on user choice

The authorization details include a scopes field that contains the scopes requested by the client (e.g., ["openid", "email", "profile"]). You should display these scopes to the user so they understand what information will be shared.

Example authorization UI#

Here's how to build a minimal authorization page at your configured path (e.g., /oauth/consent):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
// app/oauth/consent/page.tsximport { 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 = 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_ANON_KEY!,    {      cookies: {        getAll: async () => (await cookies()).getAll(),        setAll: async (cookiesToSet) => {          const cookieStore = await cookies()          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))        },      },    }  )  // Check if user is authenticated  const {    data: { user },  } = await supabase.auth.getUser()  if (!user) {    // 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>  }  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.scopes && authDetails.scopes.length > 0 && (          <div>            <strong>Requested permissions:</strong>            <ul>              {authDetails.scopes.map((scope) => (                <li key={scope}>{scope}</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>  )}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// app/api/oauth/decision/route.tsimport { 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_ANON_KEY!,    {      cookies: {        getAll: async () => (await cookies()).getAll(),        setAll: async (cookiesToSet) => {          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_to)  } 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_to)  }}

How it works#

1. User navigates to your authorization path - When a third-party app initiates OAuth, Supabase Auth redirects the user to your configured authorization path (e.g., https://example.com/oauth/consent?authorization_id=<id>)
2. Extract authorization_id - Your page extracts the authorization_id from the URL query parameters
3. Check authentication - Your page checks if the user is logged in, redirecting to login if not (preserving the authorization_id)
4. Retrieve details - Call supabase.auth.oauth.getAuthorizationDetails(authorization_id) to get information about the requesting client
5. Show consent screen - Display a UI asking the user to approve or deny access
6. Handle decision - When the user clicks approve/deny:
   • Call supabase.auth.oauth.approveAuthorization(authorization_id) or denyAuthorization(authorization_id)
   • These methods handle all OAuth logic internally (generating authorization codes, etc.)
   • They return a redirect_to URL
7. Redirect back - Redirect the user to the redirect_to URL, which sends them back to the third-party app with either an authorization code (approved) or error (denied)

Register an OAuth client#

Before third-party applications can use your project as an identity provider, you need to register them as OAuth clients.

Customizing tokens (optional)#

By default, OAuth access tokens include standard claims like user_id, role, and client_id. If you need to customize tokens—for example, to set a specific audience claim for third-party validation or add client-specific metadata—use Custom Access Token Hooks.

Custom Access Token Hooks are triggered for all token issuance, including OAuth flows. You can use the client_id parameter to customize tokens based on which OAuth client is requesting them.

Common use cases#

• Customize audience claim: Set the aud claim to the third-party API endpoint for proper JWT validation
• Add client-specific permissions: Include custom claims based on which OAuth client is requesting access
• Implement dynamic scopes: Add metadata that RLS policies can use for fine-grained access control

For more examples, see Token Security & RLS.

Redirect URI configuration#

Redirect URIs are critical for OAuth security. Supabase Auth will only redirect to URIs that are explicitly registered with the client.

Best practices#

• Use HTTPS in production - Always use HTTPS for redirect URIs in production
• Register exact, complete URLs - Each redirect URI must be the full URL including protocol, domain, path, and port if needed
• Use separate OAuth clients per environment - Create separate OAuth clients for development, staging, and production. This provides better security isolation, allows independent secret rotation, and improves auditability. If you need to use the same client across environments, you can register multiple redirect URIs, but separate clients are recommended.

Next steps#

Now that you've registered your first OAuth client, you're ready to:

• Understand OAuth flows - Learn how the authorization code and refresh token flows work
• Implement MCP authentication - Enable AI agent authentication
• Secure with RLS - Control data access for OAuth clients