Migration Path from Deprecated getTokenForConnection to exchangeToken in Auth0 Auth JS

Migrating from getTokenForConnection to exchangeToken requires only renaming the method call while preserving identical parameters, as the new unified API in auth0-auth-js v1.2.0+ handles both Token Vault and OAuth 2.0 Token Exchange flows.

The auth0/auth0-auth-js library introduced a breaking change in version 1.2.0 that deprecated the getTokenForConnection method in favor of a more flexible exchangeToken API. This migration path from deprecated getTokenForConnection to exchangeToken consolidates token exchange functionality into a single entry point while maintaining backward compatibility for existing Token Vault implementations. Understanding the exact mapping between these APIs ensures your authentication flows remain future-proof without requiring significant refactoring.

Why Migrate to exchangeToken?

The deprecation of getTokenForConnection represents more than a simple rename—it signals a strategic consolidation of Auth0's token exchange capabilities. According to the source code in packages/auth0-auth-js/src/auth-client.ts, the new method provides three critical advantages:

• Future-proof architecture – exchangeToken is now the supported entry point, while getTokenForConnection is slated for removal in a future major release
• Unified API surface – One method covers both Token Vault operations and the broader OAuth 2.0 Token Exchange specification, reducing overall API complexity
• Enhanced type safety – The new option objects provide stricter TypeScript validation and clearer error messaging than the deprecated wrapper

Understanding the exchangeToken API Architecture

The exchangeToken method accepts two distinct option shapes, automatically detecting which internal implementation to invoke based on the presence of a connection property. As implemented in auth-client.ts (lines 842–845):

public async exchangeToken(
  options: ExchangeProfileOptions | TokenVaultExchangeOptions
): Promise<TokenResponse> {
  return 'connection' in options
    ? this.#exchangeTokenVaultToken(options)   // legacy getTokenForConnection flow
    : this.#exchangeProfileToken(options);    // new token-exchange profile
}

TokenVaultExchangeOptions – Use this when exchanging a subject token (access or refresh token) for new tokens against a specific Auth0 connection. This mirrors the deprecated getTokenForConnection functionality exactly.

ExchangeProfileOptions – Use this for generic OAuth 2.0 Token Exchange profiles (e.g., urn:ietf:params:oauth:grant-type:token-exchange), supporting advanced scenarios with actor tokens, specific audiences, and custom resources.

Step-by-Step Migration Guide

1. Update Method Calls

Replace all instances of getTokenForConnection with exchangeToken. The parameter structure remains identical for Token Vault operations. As documented in types.ts (lines 227–229), the TokenVaultExchangeOptions interface preserves the same required fields:

// Before (deprecated)
const response = await authClient.getTokenForConnection({
  connection: 'my-db-connection',
  subjectToken: refreshToken,
  subjectTokenType: 'refresh_token'
});

// After (v1.2.0+)
const response = await authClient.exchangeToken({
  connection: 'my-db-connection',
  subjectToken: refreshToken,
  subjectTokenType: 'refresh_token'
});

2. Verify TypeScript and Linting Configuration

If your project uses TypeScript with noImplicitAny or employs linters that flag deprecated APIs, the compiler will now highlight getTokenForConnection calls. No runtime changes are required—the deprecation notice resides in packages/auth0-auth-js/src/errors.ts, and the method currently delegates internally to exchangeToken to maintain backward compatibility during the transition period.

3. Validate with Existing Tests

The official test suite in auth-client.spec.ts (lines 1764–2145) contains parallel test coverage for both APIs. After updating your call sites, run your existing test suite to verify that Token Vault exchanges continue functioning correctly. The test files demonstrate that both methods ultimately invoke the same underlying #exchangeTokenVaultToken private method.

Code Examples for Common Scenarios

Token Vault Exchange (Direct Replacement)

Use this pattern when migrating existing getTokenForConnection implementations:

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

const authClient = new AuthClient({
  domain: 'tenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET'
});

async function refreshAccessToken() {
  const result = await authClient.exchangeToken({
    connection: 'Username-Password-Authentication',
    subjectToken: 'existing_refresh_token_value',
    subjectTokenType: 'refresh_token',  // Required literal
    scope: 'openid profile email',      // Optional
    extra: { custom_param: 'value' }    // Optional additional params
  });

  return result.accessToken;
}

OAuth 2.0 Token Exchange Profile

Use this pattern for advanced token exchange scenarios not supported by the deprecated method:

async function performTokenExchange() {
  const result = await authClient.exchangeToken({
    grantType: 'urn:ietf:params:oauth:grant-type:token-exchange',
    subjectToken: 'existing_access_token',
    subjectTokenType: 'access_token',
    audience: 'https://api.external-service.com',
    resource: 'urn:resource:specific',
    actorToken: 'delegation_token',      // Optional for impersonation flows
    actorTokenType: 'access_token',
    scope: 'read:resources write:resources'
  });

  console.log('Exchanged token:', result.accessToken);
}

Summary

• exchangeToken replaces getTokenForConnection starting with auth0-auth-js v1.2.0, requiring only a method name change for existing Token Vault implementations
• Two option types are available: TokenVaultExchangeOptions (for connection-based exchanges) and ExchangeProfileOptions (for OAuth 2.0 Token Exchange profiles)
• Internal routing automatically selects the correct implementation based on whether the connection property exists in the options object
• Source files to reference during migration include auth-client.ts (implementation), types.ts (interfaces), and auth-client.spec.ts (validation tests)

Frequently Asked Questions

Do I need to change any parameters when migrating from getTokenForConnection to exchangeToken?

No. For Token Vault operations, the parameter names and types remain identical. Both methods accept connection, subjectToken, subjectTokenType, and optional fields like loginHint, scope, and extra. Simply rename the method call from getTokenForConnection to exchangeToken.

What version of auth0-auth-js introduced the exchangeToken method?

The exchangeToken method was introduced and getTokenForConnection was deprecated in version 1.2.0 of the auth0/auth0-auth-js package. The deprecated method remains functional in v1.2.0+ but delegates internally to exchangeToken, ensuring backward compatibility while warning developers to migrate.

Can I use exchangeToken for standard OAuth 2.0 Token Exchange profiles?

Yes. Unlike the deprecated method, exchangeToken supports the full OAuth 2.0 Token Exchange specification (RFC 8693) through the ExchangeProfileOptions interface. This allows you to specify custom grantType, actorToken, resource, and audience parameters for advanced delegation and impersonation scenarios.

Will getTokenForConnection be removed completely in future releases?

Yes. According to the deprecation notices in the source code, getTokenForConnection is scheduled for removal in a future major version release. While it currently functions as a wrapper around exchangeToken, you should complete the migration path from deprecated getTokenForConnection to exchangeToken immediately to prevent breaking changes in upcoming major releases.

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