Skip to main content

​
Function Signature

authenticateJwt(
  jwt: string,
  options?: {
    getSessionSignature?: (message: string) => Promise<string>;
  }
): Promise<void>
Available on all chain clients (DynamicEvmWalletClient, DynamicSvmWalletClient, DynamicBtcWalletClient, DynamicTonWalletClient).

​
Description

Authenticates the client with a Dynamic user JWT obtained outside the SDK — for example, by an agent that completed a Dynamic sign-in (email OTP or SIWE) on behalf of a user via createAuthClient. All wallet operations then run as that user. Unlike authenticateApiToken, no token exchange happens: the JWT is installed directly as the bearer token for all subsequent API calls. This method only validates the token’s structure (a compact JWS with three non-empty dot-separated segments); the server validates the token on every request. When getSessionSignature is provided, the client attaches a signed-session proof to key-share backup and recovery calls (backUpToDynamic: true create, backup, recovery, and sign-with-auto-recovery flows). The SDK passes messages to the callback and uses the signatures it returns — the session private key never enters the SDK. Without a signer, those calls fail with a 400 from the keyshares relay for agent JWT sessions.

​
Parameters

​
Required Parameters

  • jwt (string) - A Dynamic user JWT. Header-based (not cookie-based) JWTs are required for agent flows. To use signed sessions, the JWT must have been minted with the session public key bound in (pass sessionPublicKey at sign-in).

​
Optional Parameters

  • options.getSessionSignature ((message: string) => Promise<string>) - Signer callback for signed sessions. Must return the signature as lowercase hex — the raw 64-byte ECDSA P-256 r‖s, as produced by signSessionMessage. Other encodings, notably base64 (which can contain /), corrupt the /-delimited signed-session composite sent to the keyshares relay.

​
Returns

  • Promise<void> - Resolves once the token is installed. The signer, when provided, is kept for the life of the session and preserved across refreshAuthToken calls. A later authenticateApiToken call clears it.

​
Example

import { DynamicEvmWalletClient } from '@dynamic-labs-wallet/node-evm';
import { signSessionMessage } from '@dynamic-labs-wallet/node';

const client = new DynamicEvmWalletClient({
  environmentId: 'your-environment-id',
  enableMPCAccelerator: false, // Set to true only on AWS Nitro Enclave-compatible infrastructure
});

await client.authenticateJwt(userJwt, {
  getSessionSignature: (message) => signSessionMessage(message, privateKeyJwk),
});

​
Error Handling

try {
  await client.authenticateJwt(userJwt);
} catch (error) {
  // Thrown when the token is not a compact JWS with three segments:
  // "Invalid JWT: expected a compact JWS with three dot-separated segments"
  console.error('Authentication failed:', error);
}
An invalid but well-formed token does not fail here — the server rejects it on the first API call.
Last modified on July 9, 2026