OAuth 2.1 Provider

Install the plugin

npm install @better-auth/oauth-provider

Add the plugin to the server

Your provider signs tokens with the JWT plugin. Disable the JWT plugin's /token route, because clients call /oauth2/token instead.

import { betterAuth } from "better-auth";
import { jwt } from "better-auth/plugins";
import { oauthProvider } from "@better-auth/oauth-provider"; 

export const auth = betterAuth({
  disabledPaths: ["/token"], 
  plugins: [
    jwt(),
    oauthProvider({ 
      loginPage: "/sign-in", 
      consentPage: "/consent", 
    }), 
  ],
});

Migrate the database

To add the plugin's fields and tables to your database, run the migration or generate the schema.

npx auth migrate

See the Schema section to add the fields manually.

Expose the well-known metadata

Clients fetch your provider's metadata from the paths below, and the auth handler serves them when requests reach it. Most frameworks forward only your auth base path, such as /api/auth/*, to auth.handler. For each path outside it, such as the RFC 8414 path at the root of your domain, add a route.

The OpenID configuration is served only when scopes includes openid, which it does by default. Without a custom issuer, the issuer path is your basePath, such as /api/auth.

import { oauthProviderAuthServerMetadata } from "@better-auth/oauth-provider";
import { auth } from "@/lib/auth";

export const GET = oauthProviderAuthServerMetadata(auth);

Add the client plugins

To resume the flow after each step, add oauthProviderClient to the app that renders your login and consent pages. It carries the authorization request through sign-in and consent.

import { createAuthClient } from "better-auth/client";
import { oauthProviderClient } from "@better-auth/oauth-provider/client"; 

export const authClient = createAuthClient({
  plugins: [oauthProviderClient()], 
});

To verify access tokens in your API, use oauthProviderResourceClient; see Protect your API.

Register the API and a client

Add the API to resources, then create a client linked to it. The authorize and token endpoints reject a resource the client is not linked to; see Resources.

To create the client, call adminCreateOAuthClient. It runs only on the server and needs a signed-in user's session, so call it from a route that:

• only administrators can reach
• checks the request's Origin
• passes the request's headers

oauthProvider({
  loginPage: "/sign-in",
  consentPage: "/consent",
  resources: ["https://api.example.com"], 
})

// Inside an admin-only server route that receives `request`; check its Origin first
const client = await auth.api.adminCreateOAuthClient({
  headers: request.headers,
  body: {
    client_name: "Example App",
    redirect_uris: ["https://app.example.com/callback"],
    resources: ["https://api.example.com"],
  },
});
// Store client.client_id and client.client_secret in the client app.

To register a public client, such as a single-page or native app, add token_endpoint_auth_method: "none". The client gets no secret and authenticates with PKCE alone.

Send the user to the authorize endpoint

The client app generates a PKCE verifier, then redirects with its S256 challenge as described in RFC 7636 §4.2.

https://auth.example.com/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid profile offline_access
  &state=STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https://api.example.com

Sign in and consent

The user signs in on loginPage and approves on consentPage. The provider then redirects to redirect_uri with code, state, and iss.

Exchange the code for tokens

The client app posts the code and the PKCE verifier to the token endpoint.

curl -X POST https://auth.example.com/api/auth/oauth2/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=CODE_VERIFIER \
  -d resource=https://api.example.com

The response holds an access token for https://api.example.com, an ID token, and a refresh token.

Check the token

Call UserInfo with the access token. A 200 response with the user's sub and name means the flow worked.

curl https://auth.example.com/api/auth/oauth2/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"