getAccessToken

Retrieve access tokens with automatic refresh

The getAccessToken method retrieves the access token for the currently authenticated user, automatically refreshing it if expired and a refresh token is available.

Method Signatures

App Router

// Server Components, Server Actions, Route Handlers
await auth0.getAccessToken(
  options?: GetAccessTokenOptions
): Promise<AccessTokenResponse>

Parameters

req · IncomingMessage | NextApiRequest | NextRequest

The request object (Pages Router and middleware only)

res · ServerResponse | NextApiResponse | NextResponse

The response object (Pages Router and middleware only)

options · GetAccessTokenOptions

Optional configuration for token retrieval

interface GetAccessTokenOptions {
  refresh?: boolean;
  audience?: string;
  scope?: string;
}

Options Details

• refresh: Force token refresh even if not expired
• audience: Request token for specific API audience
• scope: Request specific scopes (for MRRT)

Returns

Returns a Promise that resolves to:

interface AccessTokenResponse {
  token: string;        // The access token
  expiresAt: number;    // Expiration timestamp (seconds since epoch)
  scope?: string;       // Granted scopes
  token_type?: string;  // Token type (usually "Bearer")
  audience?: string;    // Token audience
}

Usage Examples

App Router

Server Component

import { auth0 } from '@/lib/auth0';

export default async function Page() {
  const { token } = await auth0.getAccessToken();

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

  const data = await response.json();
  return <div>{JSON.stringify(data)}</div>;
}

Pages Router

API Route

import type { NextApiRequest, NextApiResponse } from 'next';
import { auth0 } from '@/lib/auth0';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    const { token } = await auth0.getAccessToken(req, res);

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

    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(401).json({ error: 'Unauthorized' });
  }
}

Middleware

middleware.ts

import { NextRequest, NextResponse } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  const authRes = await auth0.middleware(request);

  if (request.nextUrl.pathname.startsWith('/auth')) {
    return authRes;
  }

  try {
    const { token } = await auth0.getAccessToken(request, authRes);
    
    // Token is available and refreshed if needed
    console.log('Access token expires at:', token.expiresAt);
  } catch (error) {
    // Redirect to login if token retrieval fails
    return NextResponse.redirect(
      new URL('/auth/login', request.url)
    );
  }

  return authRes;
}

Advanced Usage

Force Token Refresh

Force a token refresh even if not expired:

const { token } = await auth0.getAccessToken({
  refresh: true
});

This is useful when user permissions or scopes have changed and you need to ensure the token reflects the latest state.

Multi-Resource Refresh Tokens (MRRT)

Request tokens for different audiences:

// Default audience
const defaultToken = await auth0.getAccessToken();

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

// With additional scopes
const adminToken = await auth0.getAccessToken({
  audience: 'https://admin.example.com',
  scope: 'read:admin write:admin'
});

When using MRRT, ensure your Auth0 Application’s Refresh Token Policies are configured with the required audiences.

Token Refresh Buffer

Refresh tokens proactively before expiration:

lib/auth0.ts

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  tokenRefreshBuffer: 60 // Refresh 60 seconds before expiry
});

Race Condition Mitigation

Check token expiry before critical operations:

const session = await auth0.getSession();

if (!session?.tokenSet?.expiresAt) {
  throw new Error('No session');
}

const BUFFER = 30; // 30 seconds
const expiresIn = session.tokenSet.expiresAt - Date.now() / 1000;

let token = session.tokenSet.accessToken;

if (expiresIn < BUFFER) {
  // Token expires soon, refresh it
  const refreshed = await auth0.getAccessToken({ refresh: true });
  token = refreshed.token;
}

// Use fresh token for API call
await fetch('https://api.example.com/critical', {
  headers: { Authorization: `Bearer ${token}` }
});

Error Handling

The method throws AccessTokenError when:

• User has no active session
• Token refresh fails
• MFA is required (throws MfaRequiredError)

import { AccessTokenError, MfaRequiredError } from '@auth0/nextjs-auth0/server';

try {
  const { token } = await auth0.getAccessToken();
} catch (error) {
  if (error instanceof MfaRequiredError) {
    // Handle MFA challenge
    console.log('MFA required:', error.mfa_token);
  } else if (error instanceof AccessTokenError) {
    // Handle other token errors
    console.error('Token error:', error.code, error.message);
  }
}

Session Persistence

When tokens are refreshed, the updated token set is automatically persisted to the session.

Server Components cannot set cookies. Calling getAccessToken() in a Server Component will refresh the token if expired, but the updated token set will not be persisted.

To ensure token updates are saved, call getAccessToken(req, res) in middleware or API routes.

Refresh Token Rotation

If your Auth0 application uses Refresh Token Rotation, configure an overlap period in the Auth0 Dashboard to prevent race conditions when multiple requests attempt to refresh tokens simultaneously.

Navigate to: Applications > Advanced Settings > OAuth

Important Notes

The response includes:

• token: The access token string
• expiresAt: Token expiration as seconds since Unix epoch
• scope: Granted scopes (if available)
• token_type: Usually “Bearer”
• audience: Token audience (if specified)

For Pages Router middleware, pass both request and response objects to ensure refreshed tokens can be read in the same request:

const { token } = await auth0.getAccessToken(request, authRes);

Related Methods

getSession

Get full session data

updateSession

Update session data