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

> Explore how the TokenResponse class parses token endpoint responses in Auth0-Auth-JS. Learn how it converts payloads into typed objects with ID token claims and expiration timestamps.

- Repository: [Auth0/auth0-auth-js](https://github.com/auth0/auth0-auth-js)
- Tags: internals
- Published: 2026-02-25

---

**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](https://github.com/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`](https://github.com/auth0/auth0-auth-js/blob/main/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`](https://github.com/auth0/auth0-auth-js/blob/main/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`.

```typescript
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.

```typescript
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`.

```typescript
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`.

```typescript
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`](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-auth-js/src/auth-client.ts).

```typescript
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`](https://github.com/auth0/auth0-auth-js/blob/main/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`](https://github.com/auth0/auth0-auth-js/blob/main/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`](https://github.com/auth0/auth0-auth-js/blob/main/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`](https://github.com/auth0/auth0-auth-js/blob/main/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.