getAccessToken (Client)

Fetch access tokens from the client side

getAccessToken is a client-side function that retrieves an access token for the currently authenticated user. It fetches tokens from the /auth/access-token endpoint, which handles token refresh automatically if needed.

This is the client-side version. For server-side token retrieval, see getAccessToken (Server).

Usage

Basic Usage

import { getAccessToken } from '@auth0/nextjs-auth0';

async function callApi() {
  const token = await getAccessToken();
  
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${token}`
    }
  });
  
  return response.json();
}

Multi-API Applications

When calling multiple APIs with different audiences, specify the audience parameter:

import { getAccessToken } from '@auth0/nextjs-auth0';

async function fetchFromMultipleApis() {
  // Get token for profile API
  const profileToken = await getAccessToken({
    audience: 'https://profile-api.example.com'
  });
  
  // Get token for orders API
  const ordersToken = await getAccessToken({
    audience: 'https://orders-api.example.com'
  });
  
  // Use the correct token for each API
  const profile = await fetch('https://profile-api.example.com/me', {
    headers: { Authorization: `Bearer ${profileToken}` }
  });
  
  const orders = await fetch('https://orders-api.example.com/orders', {
    headers: { Authorization: `Bearer ${ordersToken}` }
  });
}

Request Additional Scopes

const token = await getAccessToken({
  scope: 'read:profile write:profile'
});

Get Full Token Response

const tokenData = await getAccessToken({
  includeFullResponse: true
});

console.log(tokenData.token);       // Access token string
console.log(tokenData.expires_at);  // Expiration timestamp
console.log(tokenData.scope);       // Granted scopes
console.log(tokenData.token_type);  // Token type (e.g., "Bearer")

Signature

function getAccessToken(
  options?: AccessTokenOptions & { includeFullResponse?: false }
): Promise<string>

function getAccessToken(
  options: AccessTokenOptions & { includeFullResponse: true }
): Promise<AccessTokenResponse>

Parameters

options · AccessTokenOptions

Options for fetching the access token.

Show properties

audience · string

The unique identifier of the target API. This should match the API identifier configured in Auth0.

Critical for Multi-API Applications: If your application calls multiple APIs, you must specify this parameter to ensure the correct access token is used for each API.

Configuration Requirement: When using audience or scope, ensure that the audiences and scopes are part of your Auth0 Application’s Refresh Token Policies. This requires configuring Multi-Resource Refresh Tokens (MRRT).

const token = await getAccessToken({
  audience: 'https://api.example.com'
});

scope · string

Additional scopes to request beyond those granted during login.

Requires the Auth0 Application to be configured for Multi-Resource Refresh Tokens (MRRT).

const token = await getAccessToken({
  scope: 'read:profile write:profile'
});

includeFullResponse · boolean · default: "false"

When true, returns the full response from the /auth/access-token endpoint instead of only the access token string.

const response = await getAccessToken({
  includeFullResponse: true
});

Return Value

When includeFullResponse is false (default)

Returns a Promise<string> containing the access token.

When includeFullResponse is true

Returns a Promise<AccessTokenResponse> with the following properties:

token · string · required

The access token string.

scope · string

The scopes granted for this token.

expires_at · number

Unix timestamp (in seconds) when the token expires.

expires_in · number

Number of seconds until the token expires.

token_type · string

The token type (e.g., "Bearer", "DPoP").

Error Handling

import { getAccessToken } from '@auth0/nextjs-auth0';
import { AccessTokenError } from '@auth0/nextjs-auth0/errors';

try {
  const token = await getAccessToken();
} catch (error) {
  if (error instanceof AccessTokenError) {
    console.error('Token error:', error.code, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Configuration

By default, the function fetches from /auth/access-token. You can customize this endpoint using the NEXT_PUBLIC_ACCESS_TOKEN_ROUTE environment variable:

NEXT_PUBLIC_ACCESS_TOKEN_ROUTE=/api/custom-token

Multi-Resource Refresh Tokens (MRRT)

When using audience or scope parameters, you must configure Multi-Resource Refresh Tokens in your Auth0 Application:

1. Go to your Auth0 Application settings
2. Navigate to Advanced Settings > Grant Types
3. Enable Refresh Token
4. Configure Refresh Token Policies with the audiences and scopes your application needs

See the Auth0 MRRT documentation for more details.

Notes

• This function only works on the client side (browser)
• The user must be authenticated before calling this function
• Tokens are automatically refreshed if expired
• For server-side token retrieval, use the server-side getAccessToken method from Auth0Client