oauth-provider/api-methods

28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Delete OAuth Consent Endpoint

Endpoint: POST /oauth2/delete-consent (requires session). Takes id (consent id). Revokes a user's consent for a specific client.

Get OAuth Consent Endpoint

Endpoint: GET /oauth2/get-consent (requires session). Takes id (consent id). Returns details of a specific consent.

List OAuth Consents Endpoint

Endpoint: GET /oauth2/get-consents (requires session). Takes no parameters. Returns list of user consents.

Update OAuth Consent Endpoint

Endpoint: POST /oauth2/update-consent (requires session). Takes id (consent id) and update (OAuthConsent object). Updates a specific consent.

Create First OAuth Client Example

To create a confidential OAuth client, use: const client = await auth.api.createOAuthClient({ headers, body: { redirect_uris: [redirectUri] } }). To create a public client without a client secret, set token_endpoint_auth_method: "none".

Get OAuth Client Endpoint

Endpoint: GET /oauth2/get-client (requires session). Takes client_id as parameter. Returns client information owned by a specific user or organization.

Get Public OAuth Client Endpoint

Endpoint: GET /oauth2/public-client (requires session). Takes client_id as parameter. Returns public client fields to display on login flow pages such as consent. User must be signed in to use this endpoint.

Get Public Client Prelogin Endpoint

Endpoint: POST /oauth2/public-client-prelogin (no session required). Takes client_id and oauth_query (valid oauth query parameters sent automatically when using provided client) as parameters. Returns public client information prior to login. Must enable via allowPublicClientPrelogin: true config option.

List OAuth Clients Endpoint

Endpoint: GET /oauth2/get-clients (requires session). Takes no parameters. Returns list of clients owned by a specific user or organization.

Create OAuth Client Endpoint

Endpoint: POST /oauth2/create-client. Parameters are equivalent to RFC7591 registration endpoint. Fields restricted to admin-only editing: client_secret_expires_at (expiration time for confidential client secret), skip_consent (skip user consent flow for trusted clients), enable_end_session (allow client-initiated logout via id_token at /oauth2/end-session), metadata (additional private metadata).

Admin Create OAuth Client Example

Server-only endpoint for creating OAuth clients with restricted fields. Example: await auth.api.adminCreateOAuthClient({ headers, body: { redirect_uris: [redirectUri], client_secret_expires_at: 0, skip_consent: true, enable_end_session: true } }).

Update OAuth Client Endpoint

Endpoint: POST /oauth2/update-client (requires session). Takes client_id and update object. Cannot switch between confidential and public clients or update client_secret directly. To rotate client_secret, use rotate endpoint.

Admin Update OAuth Client Example

Server-only endpoint for updating OAuth clients with restricted fields: await auth.api.adminUpdateOAuthClient({ headers, body: { redirect_uris: [redirectUri], client_secret_expires_at: 0, skip_consent: true, enable_end_session: true } }).

Rotate Client Secret Endpoint

Endpoint: POST /oauth2/client/rotate-secret (requires session). Takes client_id. Current implementation rotates the client secret immediately and invalidates previous secret immediately.

Delete OAuth Client Endpoint

Endpoint: POST /oauth2/delete-client (requires session). Takes client_id. Deletes a user or organization's OAuth client.

Dynamic Client Registration - Basic Example

To register a new OIDC client: const client = await authClient.oauth2.register({ client_name: "My Client", redirect_uris: ["https://client.example.com/callback"] }). Parameters equivalent to RFC 7591 registration. Not yet supported: jwks and jwks_uri.

OAuth Consent Endpoint

Endpoint: POST /oauth2/consent (requires session). Takes accept (boolean to accept or deny consent) and optional scope (space-separated list of accepted scopes, if not provided originally requested scopes are accepted). When denying scopes, consent cancels and pre-existing consent remains. To remove consent, delete the user's oauthConsent for that client.

OAuth Continue Endpoint

Endpoint: POST /oauth2/continue (requires session). Takes selected (confirms account was selected), created (confirms account was registered), postLogin (confirms completion of post login activity). Sign up registration pages, account selection, and post login must be configured to perform these account steps.

OAuth Introspect Endpoint

RFC7662-compliant introspection endpoint. Provides details of provided token. If token is tied to a session, ensures session is active. To provide resource-specific claims via customAccessTokenClaims, store allowed resources that confidential client can use in its resources field.

OAuth Revoke Endpoint

RFC7009-compliant revocation endpoint. Revokes provided token. For opaque access_token: immediately removes from database, refresh_token still valid. For JWT access_token: verifies token safe to remove from client storage. For refresh_token: removes all access_tokens granted using that refresh_token and removes refresh_token to prevent further issuance.

OAuth End Session Endpoint - RP-Initiated Logout

RP-initiated logout compliant endpoint. Allows specified trusted clients to logout remotely. To enable, trusted client must be created with enable_end_session: true. If disableJwtPlugin: true, public clients cannot use this endpoint since no id_token is sent.

OAuth UserInfo Endpoint

OIDC-compliant user information endpoint at /oauth2/userinfo. Requires valid access token with at least openid scope. Returns different claims based on granted scopes: openid returns user ID (sub claim), profile returns name/picture/given_name/family_name, email returns email and email_verified. customUserInfoClaims function receives user object, requested scopes array, and access token to add additional information.

UserInfo Endpoint Example

Example of using UserInfo endpoint: const response = await fetch('https://your-domain.com/api/auth/oauth2/userinfo', { headers: { 'Authorization': 'Bearer ACCESS_TOKEN' } }); const userInfo = await response.json();

API Token Verification - better-auth Package Method

Verify tokens using verifyAccessToken from better-auth/oauth2: import { verifyAccessToken } from "better-auth/oauth2"; const payload = await verifyAccessToken(accessToken, { verifyOptions: { issuer: "https://auth.example.com", audience: "https://api.example.com" }, scopes: ["read:post"] });

API Token Verification - Resource Client Plugin Method

Verify tokens using oauthProviderResourceClient plugin: import { serverClient } from "@/lib/server-client"; const payload = await serverClient.verifyAccessToken(accessToken, { verifyOptions: { issuer: "https://auth.example.com", audience: "https://api.example.com" }, scopes: ["write:post"] });

JWT Access Token Verification

To verify JWT access tokens: validate signature using JWKS, check iss (issuer) and aud (audience) claims, verify exp (expiration) and nbf claim if sent, validate appropriate scope for each endpoint.

Opaque Access Token Verification

To verify opaque access tokens: send received token to /oauth2/introspect and assert active: true is returned, validate appropriate scope for each endpoint.

JWT vs Opaque Access Tokens - Recommendation

Simplest approach is to only accept JWT-formatted access tokens and deny opaque tokens. Benefits: fast (locally verifiable, no network call), future-proof (independent of auth server after issuance), no client secret needed. Accepting both JWT and opaque tokens is possible but trade-offs: immediate validation possible, client doesn't require resource parameter, but DOS vulnerability if external clients, performance impact from network calls, secret required for introspection.

Give your agent this brain