Authenticate with an external JWT

Sign users into Dynamic with a JWT issued by your own authentication provider.

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Bring Your Own Auth (BYOA) is an enterprise feature. Contact us in Slack or at [e-mail] to enable it.

If you already issue your own JWTs (e.g. from Auth0, Firebase Auth, Supabase, or your own backend), you can exchange that JWT for a Dynamic session. After sign-in, the user behaves like any other Dynamic user — with access to wallets, user management, and the rest of the SDK.

For concepts and configuration, see Bring Your Own Auth.

Issue a Dynamic-specific JWT from your auth provider — separate from your application’s normal access token — so the token Dynamic receives cannot be used to access resources on your own servers. See Bring Your Own Auth for the full recommendation.

Prerequisites

• BYOA configured in your Dynamic dashboard (issuer, JWKS URL).
• DynamicContextProvider set up with your environment ID.
• Your backend issues a JWT with at least iss, sub, and exp claims.

Usage

Use the signInWithExternalJwt method from the useExternalAuth hook. Dynamic verifies the signature against your configured JWKS URL, validates the claims, and establishes a session.

React

import { useExternalAuth } from '@dynamic-labs/sdk-react-core';

const SignInButton = ({ externalJwt, externalUserId }) => {
  const { signInWithExternalJwt } = useExternalAuth();

  const handleSignIn = async () => {
    try {
      const userProfile = await signInWithExternalJwt({
        externalJwt,
        externalUserId,
      });

      if (userProfile) {
        // The user is now signed into Dynamic
      }
    } catch (e) {
      console.error('Dynamic sign-in failed:', e);
    }
  };

  return <button onClick={handleSignIn}>Sign in</button>;
};

Parameters

Parameter	Type	Required	Description
externalJwt	string	Yes	The raw encoded JWT issued by your authentication provider.
externalUserId	string	Yes	The user ID in your authentication system. Must match the sub claim in the JWT — Dynamic derives the stored external user ID from the JWT server-side.

Returns a UserProfile on success.

Related

• Bring Your Own Auth — Concepts, configuration, and JWT requirements.
• useExternalAuth — Full hook reference.
• External auth step-up — Issue elevated access tokens from your backend for sensitive actions.