Skip to main content
The oauth() plugin adds social sign-in to theAuth using the OAuth 2.0 authorization code flow with PKCE (S256). It handles the token exchange, account linking, and session creation.
oauth() issues a session on a successful callback, so auth.session must be configured in createTheAuth. Without it the plugin throws on startup.

Built-in providers

Each provider is a factory exported from @glinr/theauth/auth. Pass the resulting instances to oauth() as a map keyed by provider ID.

Google

GitHub

Apple

Discord

Slack

Microsoft

GitLab

LinkedIn

Other first-class factories (createXProvider({ clientId, clientSecret, scopes?, redirectUri? })) exist for Atlassian, Dropbox, Figma, Notion, Reddit, Spotify, Twitch, Twitter / X, and Zoom. Additional services (Facebook, Bitbucket, Yahoo, LINE, Coinbase, and others) have preset helpers such as facebookProvider(clientId, clientSecret, scopes?), and Auth0, Okta, and Cognito take the tenant domain first: auth0Provider(domain, clientId, clientSecret, scopes?). See the individual provider pages.

Generic setup

lib/theauth.ts
providers is a Record<string, OAuthProvider>. The key is the provider ID used in the URLs below. The session secret must be at least 32 characters. The callback URL you register with each provider is:
baseUrl is the public URL where theAuth is served. When you mount theAuth under an adapter prefix such as /api/theauth, include the prefix in baseUrl (for example https://your-app.com/api/theauth), so the URL registered with the provider is https://your-app.com/api/theauth/auth/oauth/callback/google. To compute a different redirect URI, pass buildRedirectUri: (provider, baseUrl) => string to oauth(). A provider can also carry its own redirectUri override.

Endpoints

The plugin registers these routes (relative to the adapter prefix):
A browser is redirected through the theAuth handler to an OAuth provider, comes back with a code, and theAuth sets a session cookie.

Web sign-in: redirect out, code back, session cookie set.

The sign-in flow

  1. Your frontend navigates to /auth/oauth/authorize/{provider}. theAuth generates a random state and a PKCE verifier, stores both in the database (default lifetime 10 minutes, set with stateTtlSeconds), and redirects to the provider with the S256 challenge.
  2. The provider redirects back to /auth/oauth/callback/{provider} with an authorization code and the state.
  3. theAuth validates and consumes the state, exchanges the code for tokens, and fetches the user profile.
  4. theAuth finds the user by email or creates one and links the provider account. It then asks the sign-in gate whether a session may be issued. If so it sets the theauth_session cookie and redirects to {baseUrl}/?auth_user=<url-encoded JSON with id and email>. If the user must change their password or pass a second factor, it redirects to {baseUrl}/ with the challenge in the URL fragment and sets no cookie.
The provider account is identified by the provider’s own user ID, so the same provider account always resolves to the same linked row.
Every first-class provider sends the PKCE challenge except Notion, which does not support PKCE. GitHub accepts the parameter and ignores it.

Account linking

When the email returned by the provider matches an existing user, theAuth links the provider account to that user only if the provider says the address is verified and the existing user’s address is verified too. If either side is unverified, the callback answers 409 and links nothing: the user signs in with their existing method and links the provider from account settings. This stops account pre-hijacking, where someone registers a victim’s address first and keeps access after the victim signs in with a provider. Otherwise it creates a new user, with the email marked verified only when the provider vouched for it. Providers that do not report verification (Microsoft, Linear, Cloudflare, PayPal, Kick, Spotify and Apple) never link by email. A user can have several linked providers. Only the email and name are copied onto the user record; the avatar is not stored. Apps that need the old behavior can set unsafeAllowUnverifiedEmailLinking: true on oauth(). It links by email whatever either side says, so only use it when every sign-up path of your app verifies addresses first. If a provider returns no email (Reddit, for example), the callback cannot match or create a user. The account row stays unassigned and the callback responds with JSON (isNewAccount, account, userInfo) instead of a session.
Auto-linking trusts the email reported by the provider and cannot be turned off. If your threat model requires stronger guarantees, only enable providers that verify email addresses.
The plugin adds GET /auth/oauth/accounts and DELETE /auth/oauth/accounts/:provider, and exposes the OAuth module as theauth.plugins.getContext().oauth. From it you get getAccessToken (with refresh), listAccounts and unlinkAccount. See Social token API. To work with the module without the plugin, build it with createOAuthModule(db, { providers }).

Custom providers

Any OIDC-compliant provider works with the generic factory genericOIDC. Supply an issuer to use discovery, or supply explicit endpoints to skip it:
genericOIDC reads sub, email, name, and picture from the userinfo response and fails if sub or email is missing. For a provider whose profile endpoint does not return those claims, implement the OAuthProvider interface yourself (getAuthorizationUrl, exchangeCode, and getUserInfo, which returns { id, email, name?, avatar?, raw }) and put the instance in providers.

Google

Sign in with Google using OIDC, the most common provider.

GitHub

OAuth 2.0 for GitHub with optional org and email scopes.

Authentication overview

All sign-in methods available in theAuth.

OIDC provider

Turn theAuth itself into an OpenID Connect identity provider.

Native app sign-in

Set mobile.redirectUris to let a native app finish the flow in the system browser (RFC 8252 with PKCE):
mobile_redirect must match an entry in redirectUris exactly, and the challenge is required. A wrong verifier burns the code. Failures are returned to the app as ?error=, and a required second factor arrives as the usual #gate=... fragment on the app URI. The code is stored in theauth_one_time_tokens, which createTheAuth now creates whenever the oauth plugin is registered. The Expo guide shows the client side.
Last modified on October 19, 2026