# Migration Path from Deprecated getTokenForConnection to exchangeToken in Auth0 Auth JS

> Migrate from getTokenForConnection to exchangeToken in Auth0 Auth JS with ease. Learn the simple renaming process and leverage the new unified API in v1.2.0+ for seamless token exchange.

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

---

**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`](https://github.com/auth0/auth0-auth-js/blob/main/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`](https://github.com/auth0/auth0-auth-js/blob/main/auth-client.ts) (lines 842–845):

```typescript
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`](https://github.com/auth0/auth0-auth-js/blob/main/types.ts) (lines 227–229), the `TokenVaultExchangeOptions` interface preserves the same required fields:

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

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

```typescript
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`](https://github.com/auth0/auth0-auth-js/blob/main/auth-client.ts) (implementation), [`types.ts`](https://github.com/auth0/auth0-auth-js/blob/main/types.ts) (interfaces), and [`auth-client.spec.ts`](https://github.com/auth0/auth0-auth-js/blob/main/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.