getAccessToken (Client)

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:

Go to your Auth0 Application settings
Navigate to Advanced Settings > Grant Types
Enable Refresh Token
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

Client

Server

Errors

Types

Usage

Basic Usage

Multi-API Applications

Request Additional Scopes

Get Full Token Response

Signature

Parameters

Return Value

When `includeFullResponse` is `false` (default)

When `includeFullResponse` is `true`

Error Handling

Configuration

Multi-Resource Refresh Tokens (MRRT)

Notes

Build docs developers (and LLMs) love

Client

Server

Errors

Types

Documentation Index

​Usage

​Basic Usage

​Multi-API Applications

​Request Additional Scopes

​Get Full Token Response

​Signature

​Parameters

​Return Value

​When includeFullResponse is false (default)

​When includeFullResponse is true

​Error Handling

​Configuration

​Multi-Resource Refresh Tokens (MRRT)

​Notes

Build docs developers (and LLMs) love

Usage

Basic Usage

Multi-API Applications

Request Additional Scopes

Get Full Token Response

Signature

Parameters

Return Value

When `includeFullResponse` is `false` (default)

When `includeFullResponse` is `true`

Error Handling

Configuration

Multi-Resource Refresh Tokens (MRRT)

Notes