refreshAuthToken

Refreshes the Dynamic user JWT using the current session, installs the replacement, and returns it

Function Signature

refreshAuthToken(): Promise<string>

Available on all chain clients (DynamicEvmWalletClient, DynamicSvmWalletClient, DynamicBtcWalletClient, DynamicTonWalletClient).

Description

Refreshes the Dynamic user JWT using the current session and installs the new token for all subsequent API calls. Returns the new JWT so you can persist it — the previous token is superseded, so overwrite your stored copy on every call.

The server enforces a hard refresh limit through the JWT’s refreshExp claim. Once reached, refresh fails with a 401 and the user must sign in again; refresh cannot extend a session indefinitely without the user re-approving.

The session signer passed to authenticateJwt is preserved across refreshes.

Parameters

None.

Returns

• Promise<string> - The new JWT, already installed on the client.

Example

const refreshedJwt = await client.refreshAuthToken();
// Overwrite the stored JWT with refreshedJwt.

Error Handling

try {
  const refreshedJwt = await client.refreshAuthToken();
} catch (error) {
  // - Not authenticated: "Client must be authenticated before making API calls.
  //   Call authenticateApiToken or authenticateJwt first."
  // - Refresh limit (refreshExp) reached or session invalid: the request fails
  //   with a 401. Run the sign-in flow again and call authenticateJwt.
  // - Cookie-auth environment: "Token refresh returned no JWT. The environment
  //   may be configured for cookie-based auth; agent flows require header-based
  //   JWTs."
  console.error('Refresh failed:', error);
}

Related Functions

• authenticateJwt() - Install a user JWT
• createAuthClient() - Sign the user in again when the refresh limit is reached