How the TokenResponse Class Parses Token Endpoint Responses in Auth0-Auth-JS

The TokenResponse class converts raw OAuth 2.0 token endpoint payloads into strongly-typed objects by extracting ID token claims, calculating absolute expiration timestamps, and mapping standard fields like access_token and refresh_token through its static fromTokenEndpointResponse factory method.

The TokenResponse class is a core component of the auth0/auth0-auth-js repository, responsible for transforming low-level OpenID Connect responses into developer-friendly JavaScript objects. Located in packages/auth0-auth-js/src/types.ts, this class ensures that every token exchange—whether from an authorization code flow, client credentials grant, or CIBA request—returns consistent, type-safe data that the SDK can consume downstream.

Understanding the TokenResponse Class Structure

The TokenResponse class definition spans lines 500–589 in packages/auth0-auth-js/src/types.ts. It exposes strongly-typed properties including accessToken, idToken, refreshToken, expiresAt, scope, claims, authorizationDetails, tokenType, and issuedTokenType.

Rather than exposing a public constructor for direct instantiation, the class provides a static factory method named fromTokenEndpointResponse. This method accepts a raw TokenEndpointResponse object from the underlying OpenID client and orchestrates the parsing logic.

The fromTokenEndpointResponse Factory Method

The static fromTokenEndpointResponse method performs a five-step transformation process to convert raw OAuth 2.0 responses into structured TokenResponse instances.

Step 1: Extracting ID Token Claims

When the raw response contains an id_token, the parser decodes the JWT to extract user claims. It invokes the claims() method on the underlying response object, which returns an IDToken object containing standardized identity assertions like sub, iss, aud, and exp.

const claims = response.id_token ? response.claims() : undefined;

If no ID token is present, the claims property remains undefined.

Step 2: Calculating Absolute Expiration Time

OAuth 2.0 token endpoints return expires_in as a relative value representing seconds until expiration. The parser converts this to an absolute Unix timestamp by adding the relative duration to the current time.

const expiresAt = Math.floor(Date.now() / 1000) + Number(response.expires_in);

This calculation produces the expiresAt property, enabling downstream logic to check token validity without recalculating relative offsets.

Step 3: Instantiating the TokenResponse

With the derived values calculated, the method constructs a new TokenResponse instance. It passes the mandatory access_token and calculated expiresAt, followed by optional fields including id_token, refresh_token, scope, the decoded claims, and authorization_details.

const tokenResponse = new TokenResponse(
  response.access_token,
  expiresAt,
  response.id_token,
  response.refresh_token,
  response.scope,
  claims,
  response.authorization_details
);

Step 4: Populating Extended Metadata

After construction, the parser assigns additional protocol metadata that does not participate in the constructor signature. It maps the token_type (typically "Bearer") and, for token exchange flows per RFC 8693, the issued_token_type.

tokenResponse.tokenType = response.token_type;
tokenResponse.issuedTokenType = (response as any).issued_token_type;

Step 5: Returning the Fully-Typed Object

The method returns the populated TokenResponse instance, which now exposes strongly-typed properties for all standard OAuth 2.0 and OIDC fields. This object propagates through the SDK to AuthClient methods and server-side state utilities.

Practical Usage Example

The following example demonstrates how TokenResponse.fromTokenEndpointResponse operates within a complete authentication flow using the AuthClient class defined in packages/auth0-auth-js/src/auth-client.ts.

import { AuthClient, TokenResponse } from '@auth0/auth0-auth-js';

// Initialize the client
const authClient = new AuthClient({
  domain: 'tenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
});

// Complete an authorization code flow
const tokenEndpointResponse = await authClient.getTokenByCode(
  new URL('https://app.example.com/callback?code=AUTH_CODE&state=xyz'),
  { redirect_uri: 'https://app.example.com/callback' }
);

// Parse into strongly-typed TokenResponse
const token: TokenResponse = TokenResponse.fromTokenEndpointResponse(
  tokenEndpointResponse
);

// Access parsed properties
console.log('Access Token:', token.accessToken);
console.log('Expires At:', token.expiresAt);
console.log('Scopes:', token.scope);

if (token.idToken) {
  console.log('User ID:', token.claims?.sub);
  console.log('Issuer:', token.claims?.iss);
}

Integration Across the SDK

The TokenResponse.fromTokenEndpointResponse method serves as the central parsing utility throughout the Auth0 JavaScript SDK. According to the source code in packages/auth0-auth-js/src/auth-client.ts, this factory method is invoked by multiple high-level authentication methods:

• AuthClient.backchannelAuthentication – Parses CIBA (Client Initiated Backchannel Authentication) token responses
• AuthClient.exchangeToken – Handles RFC 8693 token exchange responses, including external provider exchanges
• AuthClient.getTokenByCode – Processes authorization code flow responses

Additionally, server-side implementations in packages/auth0-server-js/src/state/utils.ts consume TokenResponse objects to persist token sets in session stores, demonstrating the class's role in both client and server contexts.

Summary

• The TokenResponse class in packages/auth0-auth-js/src/types.ts provides a strongly-typed representation of OAuth 2.0 token endpoint responses.
• The static fromTokenEndpointResponse factory method handles all parsing logic, converting raw TokenEndpointResponse objects into structured instances.
• Parsing involves extracting ID token claims via response.claims(), calculating absolute expiration timestamps, and mapping standard fields like access_token, refresh_token, and scope.
• Extended metadata including token_type and RFC 8693 issued_token_type are assigned post-construction.
• The class is utilized across the SDK in AuthClient methods and server-side state management utilities.

Frequently Asked Questions

What fields does the TokenResponse class extract from the token endpoint?

The TokenResponse class extracts all standard OAuth 2.0 and OpenID Connect fields including access_token, id_token, refresh_token, expires_in, scope, and token_type. It also captures RFC 8693-specific fields like issued_token_type and authorization_details when present in the response.

How does TokenResponse handle ID token parsing?

When the raw response contains an id_token, the fromTokenEndpointResponse method invokes response.claims() to decode the JWT payload. This produces an IDToken object containing standard claims such as sub, iss, aud, and exp, which is stored in the claims property of the resulting TokenResponse instance.

Where is the TokenResponse class defined in the Auth0 SDK?

The TokenResponse class is defined in packages/auth0-auth-js/src/types.ts within the auth0/auth0-auth-js repository. The parsing logic resides in the static fromTokenEndpointResponse method, which spans approximately lines 500–589 of that file according to the source analysis.

Can I use TokenResponse outside of AuthClient methods?

Yes, while TokenResponse.fromTokenEndpointResponse is primarily invoked internally by AuthClient methods such as getTokenByCode, exchangeToken, and backchannelAuthentication, you can import and use it directly when working with raw TokenEndpointResponse objects from custom implementations or external OpenID clients.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}