Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuxt-alt/auth/llms.txt

Use this file to discover all available pages before exploring further.

The oauth2 scheme implements the full OAuth2 authorization flow, supporting the authorization code grant with PKCE (S256 or plain), the implicit token flow, and refresh token rotation. It handles the complete redirect-and-callback lifecycle, exchanges authorization codes for access tokens, stores and renews tokens automatically, and fetches the user profile from a configurable userinfo endpoint. Use it to integrate with any standards-compliant OAuth2 provider such as GitHub, Google, Auth0, or Okta.

​
Configuration

nuxt.config.ts
export default defineNuxtConfig({
  auth: {
    strategies: {
      github: {
        scheme: 'oauth2',
        clientId: 'YOUR_CLIENT_ID',
        scope: ['read:user'],
        endpoints: {
          authorization: 'https://github.com/login/oauth/authorize',
          token:         'https://github.com/login/oauth/access_token',
          userInfo:      'https://api.github.com/user',
          logout:        false,
        },
        responseType:        'code',
        grantType:           'authorization_code',
        codeChallengeMethod: 'S256',
        redirectUri:         'https://yourapp.com/login',
      },
    },
  },
})

​
Endpoints

​
endpoints.authorization
string
required
The OAuth2 authorization URL. The user is redirected here to grant access. This is the only required endpoint.
​
endpoints.token
string
The token exchange endpoint. Required when using the authorization_code grant type. The scheme makes a POST request here to exchange an authorization code for an access token.Default: undefined
​
endpoints.userInfo
string
The userinfo endpoint URL. The scheme makes an authenticated GET request here to populate the user object after a successful token exchange. When not set, the user object is left empty.Default: undefined
​
endpoints.logout
string | false
The logout redirect URL. When set, the user is redirected here (with client_id and redirect_uri query parameters appended) on logout. Set to false or leave unset to perform only a local session reset without a provider redirect.Default: undefined

​
OAuth2 Flow

​
responseType
string
The OAuth2 response_type parameter sent in the authorization request. Common values are 'code' (authorization code grant), 'token' (implicit grant), 'id_token', or 'none'.Default: 'token'
​
grantType
string
The OAuth2 grant_type sent during the token exchange request. Typical values are 'authorization_code', 'client_credentials', 'password', or 'refresh_token'.Default: undefined
​
responseMode
string
The JARM (JWT Secured Authorization Response Mode) mode. Accepted values are 'query.jwt', 'fragment.jwt', 'form_post.jwt', and 'jwt'. Leave unset for standard responses.Default: undefined
​
codeChallengeMethod
'S256' | 'plain' | 'implicit' | false
The PKCE code challenge method. Use 'S256' for SHA-256 hashed challenges (recommended), 'plain' for unencoded challenges, or false to disable PKCE entirely.Default: false
​
scope
string | string[]
The OAuth2 scopes to request. May be provided as a space-delimited string or an array of scope names. Arrays are joined with a space before being sent to the provider.Default: []
​
state
string
A custom state string included in the authorization request. When not set, a random 10-character string is generated automatically for CSRF protection.Default: auto-generated
​
acrValues
string
Authentication Context Class Reference values forwarded as acr_values in the authorization request. Used by some enterprise identity providers to request specific authentication assurance levels.Default: undefined
​
audience
string
The intended audience of the access token. Required by some providers (e.g. Auth0) to scope the token to a specific API.Default: undefined

​
Client

​
clientId
string
required
Your OAuth2 application’s client ID, issued by the provider when you register the application.
​
clientSecretTransport
'body' | 'aurthorization_header'
Controls how the client secret is sent during the token exchange. 'body' includes it as a form field; 'aurthorization_header' uses HTTP Basic authentication.Default: 'body'
​
redirectUri
string
The callback URI registered with the OAuth2 provider. When not set, the scheme auto-computes it from the app’s baseURL and the redirect.callback path configured in auth.options.redirect.Default: auto-computed
​
logoutRedirectUri
string
The URI the provider should redirect the user to after logout. When not set, the scheme auto-computes it from the app’s origin and the redirect.logout path.Default: auto-computed
​
accessType
'online' | 'offline'
Google’s access_type parameter. Use 'offline' to request a refresh token from Google’s OAuth2 server.Default: undefined
By default the OAuth2 scheme redirects the entire page to the provider. Setting clientWindow: true opens the provider’s authorization page in a popup instead, leaving the parent page in place. After the user approves access, the popup posts a message back to the parent and closes automatically.
​
clientWindow
boolean
When true, opens the OAuth2 authorization flow in a popup window instead of redirecting the current page.Default: false
​
clientWindowWidth
number
Width of the popup window in pixels.Default: 400
​
clientWindowHeight
number
Height of the popup window in pixels.Default: 600
strategies: {
  google: {
    scheme: 'oauth2',
    clientId: 'YOUR_CLIENT_ID',
    clientWindow: true,       // opens a popup instead of redirecting
    clientWindowWidth: 500,
    clientWindowHeight: 700,
    scope: ['profile', 'email'],
    endpoints: {
      authorization: 'https://accounts.google.com/o/oauth2/auth',
      token:         'https://oauth2.googleapis.com/token',
      userInfo:      'https://www.googleapis.com/oauth2/v3/userinfo',
    },
    responseType: 'code',
    grantType:    'authorization_code',
  },
}
Safari blocks popup windows that are opened after an await call. The scheme opens the window synchronously on the first loginWith call to satisfy Safari’s user gesture requirement.

​
Token

​
token.property
string
The dot-notation path in the token exchange (or refresh) response where the access token lives.Default: 'access_token'
​
token.expiresProperty
string
The dot-notation path in the token response for the access token’s lifetime in seconds. Used when token.maxAge is false.Default: 'expires_in'
​
token.type
string | false
The prefix prepended to the token value when setting the authorization header (e.g. 'Bearer mytoken123'). Set to false to send the raw token without a prefix.Default: 'Bearer'
​
token.name
string
The HTTP request header used to carry the token.Default: 'Authorization'
​
token.maxAge
number | false
Override the token lifetime in seconds, ignoring any value returned by the server. When false, the scheme reads token.expiresProperty from the token response instead.Default: false
​
token.global
boolean
When true, the token is automatically attached to every outgoing HTTP request via the request interceptor.Default: true
​
token.prefix
string
The key prefix used when persisting the token in storage.Default: '_token.'
​
token.expirationPrefix
string
The key prefix used when persisting the token expiration timestamp in storage.Default: '_token_expiration.'
​
token.httpOnly
boolean
When true, the access token is expected to be managed by a server-side httpOnly cookie rather than stored in JavaScript-accessible storage.Default: false

​
User

​
user.property
string | false
The dot-notation path within the userInfo endpoint response that contains the user object. Set to false if the entire response body is the user object.Default: false

​
Refresh Token

​
refreshToken.property
string | false
The dot-notation path in the token exchange (or refresh) response where the refresh token lives. Set to false if the provider does not return a refresh token.Default: 'refresh_token'
​
refreshToken.maxAge
number | false
The refresh token’s lifetime in seconds. Used to determine when the refresh token itself has expired and a new authorization flow is required.Default: 2592000 (30 days)
​
refreshToken.prefix
string
The key prefix used when persisting the refresh token in storage.Default: '_refresh_token.'
​
refreshToken.expirationPrefix
string
The key prefix used when persisting the refresh token expiration timestamp in storage.Default: '_refresh_token_expiration.'
​
refreshToken.httpOnly
boolean
When true, the refresh token is expected to be stored in a server-managed httpOnly cookie. The scheme omits the refresh token from request bodies, relying on the browser to send the cookie automatically.Default: false

​
Other Options

​
autoLogout
boolean
When true, the scheme resets the session on mount if the access token has expired and cannot be refreshed (e.g. the refresh token has also expired or is unavailable).Default: false
​
organization
string
An organization identifier forwarded as the organization parameter in the authorization request. Used by Auth0 and some Okta configurations.Default: undefined

​
Triggering Login Programmatically

Calling loginWith on an OAuth2 strategy initiates the provider redirect (or popup). No credentials are needed — the provider handles authentication: 
const auth = useAuth()

// Redirects the page to the OAuth provider's authorization URL
await auth.loginWith('github')
To pass additional authorization parameters: 
await auth.loginWith('github', {
  params: {
    prompt: 'consent',
  },
})
The OAuth2 callback route (default: /login) must be publicly accessible without authentication. Mark the page with definePageMeta({ auth: false }) to prevent the auth middleware from redirecting unauthenticated users away before the callback can be processed.

Build docs developers (and LLMs) love

Get started for freeTalk to us