Bring Your Own Auth

This page has been updated for Wallets SDK V1. If you are using the previous version, see the previous version of this page or the V1 migration guide.

Crossmint provides connectors for the most popular auth providers, including Auth0, Firebase, Supabase, Stytch, Cognito, and Kinde. When you bring your own auth, Crossmint automatically extracts the user ID from your provider’s JWT and assigns it to the wallet’s owner property. Wallet creation, transaction signing, and balance reads all work the same way regardless of which auth provider you use. If you are just getting started or prototyping, Crossmint Auth is a great way to move fast in staging before connecting your own provider.

Prerequisites

API Key: Ensure you have an API key with the scopes: wallets.create.

Using your own auth provider

React
React Native
Kotlin
Swift
Flutter

Configure JWT Authentication in the Crossmint Console

Navigate to your project in the Crossmint Console.
Go to the API Keys section from the sidebar.
Scroll down to the JWT authentication section.
Choose your preferred authentication method:

3P Auth providers: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
Custom tokens: Opt to issue and manage your own JWTs.

After making your selection and providing any necessary details, click Save JWT auth settings to apply your configuration.

Add the Crossmint providers to your app

Add the necessary Crossmint providers to your app together with your own auth provider.

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintWalletProvider,
    useCrossmint,
} from "@crossmint/client-sdk-react-ui";

import { YourAuthProvider, useYourAuthProviderHook } from "@your-auth-provider";

export function Providers({ children }: { children: React.ReactNode }) {
    return (
        <YourAuthProvider>
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintWalletProvider>
                    <JwtSync />
                    {children}
                </CrossmintWalletProvider>
            </CrossmintProvider>
        </YourAuthProvider>
    );
}

// Get the JWT from your auth provider and pass it to the Crossmint provider
function JwtSync() {
    const { jwt } = useYourAuthProviderHook();
    const { setJwt } = useCrossmint();

    useEffect(() => {
        setJwt(jwt);
    }, [jwt]);

    return null;
}

Pass the JWT and create or retrieve the wallet

Once the JWT is available, use getWallet to retrieve an existing wallet. If no wallet exists, it throws a WalletNotAvailableError — catch it and call createWallet instead.

"use client";

import { useYourAuthProviderHook } from "@your-auth-provider";
import { useEffect } from "react";
import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-ui";
import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

export function YourComponent() {
    const { email } = useYourAuthProviderHook();
    const { jwt } = useCrossmint();
    const { getWallet, createWallet } = useWallet();

    useEffect(() => {
        if (email != null && jwt != null) {
            getWallet({ chain: "base-sepolia" }).catch((error) => {
                if (error instanceof WalletNotAvailableError) {
                    createWallet({
                        chain: "base-sepolia",
                        recovery: { type: "email", email },
                    }).catch(console.error);
                }
            });
        }
    }, [email, jwt]);

    // your component logic here
    return (
        <div>
            <h1>Your Component</h1>
        </div>
    );
}

getOrCreateWallet has been removed in V1. Use getWallet to retrieve an existing wallet. If it throws a WalletNotAvailableError, call createWallet instead. See the migration guide for details.

See the React SDK reference for more details on providers and hooks.

Configure JWT Authentication in the Crossmint Console

Navigate to your project in the Crossmint Console.
Go to the API Keys section from the sidebar.
Scroll down to the JWT authentication section.
Choose your preferred authentication method:

3P Auth providers: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
Custom tokens: Opt to issue and manage your own JWTs.

After making your selection and providing any necessary details, click Save JWT auth settings to apply your configuration.

Add the Crossmint providers to your app

Add the necessary Crossmint providers to your app together with your own auth provider.

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintWalletProvider,
    useCrossmint,
} from "@crossmint/client-sdk-react-native-ui";

import { YourAuthProvider, useYourAuthProviderHook } from "@your-auth-provider";

type ProvidersProps = {
    children: React.ReactNode;
};

export default function Providers({ children }: ProvidersProps) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <YourAuthProvider>
                <CrossmintWalletProvider>
                    <JwtSync />
                    {children}
                </CrossmintWalletProvider>
            </YourAuthProvider>
        </CrossmintProvider>
    );
}

// Get the JWT from your auth provider and pass it to the Crossmint provider
function JwtSync() {
    const { jwt } = useYourAuthProviderHook();
    const { setJwt } = useCrossmint();

    useEffect(() => {
        setJwt(jwt);
    }, [jwt]);

    return null;
}

Pass the JWT and create or retrieve the wallet

Once the JWT is available, use getWallet to retrieve an existing wallet. If no wallet exists, it throws a WalletNotAvailableError — catch it and call createWallet instead.

import { useYourAuthProviderHook } from "@your-auth-provider";
import { useEffect } from "react";
import { View, Text } from "react-native";
import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-native-ui";
import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

export function YourAuthComponent() {
    const { email } = useYourAuthProviderHook();
    const { jwt } = useCrossmint();
    const { getWallet, createWallet } = useWallet();

    useEffect(() => {
        if (jwt != null && email != null) {
            getWallet({ chain: "base-sepolia" }).catch((error) => {
                if (error instanceof WalletNotAvailableError) {
                    createWallet({
                        chain: "base-sepolia",
                        recovery: { type: "email", email },
                    }).catch(console.error);
                }
            });
        }
    }, [jwt, email]);

    // your component logic here
    return (
        <View>
            <Text>Your Auth Component</Text>
        </View>
    );
}

getOrCreateWallet has been removed in V1. Use getWallet to retrieve an existing wallet. If it throws a WalletNotAvailableError, call createWallet instead. See the migration guide for details.

See the React Native SDK reference for more details on providers and hooks.

Configure JWT Authentication in the Crossmint Console

Navigate to your project in the Crossmint Console.
Go to the API Keys section from the sidebar.
Scroll down to the JWT authentication section.
Choose your preferred authentication method and save your settings.

Set up the SDK with your JWT

Initialize the SDK in your Application.onCreate and pass your provider’s JWT to the auth manager.

import com.crossmint.kotlin.sdk.Crossmint
import com.crossmint.kotlin.auth.CrossmintAuthManager
import com.crossmint.kotlin.auth.models.AuthToken

// In Application.onCreate:
Crossmint.shared(apiKey = "YOUR_CROSSMINT_API_KEY", appContext = this)

// In your composable or ViewModel:
val sdk = LocalCrossmintSDK.current
val authManager = sdk.authManager as CrossmintAuthManager

// Pass the JWT from your auth provider
authManager.authenticateWithToken(
    AuthToken(
        jwt = "YOUR_PROVIDER_JWT",
        refreshToken = "YOUR_REFRESH_TOKEN",
        userEmail = "user@example.com"
    )
)

Create or retrieve the wallet

Once authenticated, create or retrieve the wallet.

import com.crossmint.kotlin.types.EVMChain
import com.crossmint.kotlin.signers.SignerType

val wallet = sdk.crossmintWallets.getWallet(chain = EVMChain.BaseSepolia)
    .getOrNull()
    ?: sdk.crossmintWallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recovery = SignerType.Email("user@example.com")
    ).getOrThrow()

println("Wallet address: ${wallet.address}")

Configure JWT Authentication in the Crossmint Console

Navigate to your project in the Crossmint Console.
Go to the API Keys section from the sidebar.
Scroll down to the JWT authentication section.
Choose your preferred authentication method and save your settings.

Set up the SDK with your JWT

Initialize the SDK and pass your provider’s JWT to the auth manager before creating or fetching a wallet.

import CrossmintAuth
import CrossmintClient

// Initialize the auth manager
let authManager = try CrossmintAuthManager(apiKey: crossmintApiKey)

// Pass the JWT from your auth provider
await authManager.setJWT("YOUR_PROVIDER_JWT")

// Initialize the SDK with the auth manager
let sdk = CrossmintSDK.shared(
    apiKey: crossmintApiKey,
    authManager: authManager
)

Create or retrieve the wallet

Once the JWT is set, create or retrieve the wallet as usual.

let wallet: EVMWallet
if let existing = try await sdk.crossmintWallets.getWallet(
    chain: EVMChain.baseSepolia,
    recovery: EVMSigners.email("user@example.com")
) {
    wallet = existing
} else {
    wallet = try await sdk.crossmintWallets.createWallet(
        chain: EVMChain.baseSepolia,
        recovery: EVMSigners.email("user@example.com")
    )
}
print("Wallet address:", wallet.address)

Configure JWT Authentication in the Crossmint Console

Navigate to your project in the Crossmint Console.
Go to the API Keys section from the sidebar.
Scroll down to the JWT authentication section.
Choose your preferred authentication method:

3P Auth providers: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
Custom tokens: Opt to issue and manage your own JWTs.

After making your selection and providing any necessary details, click Save JWT auth settings to apply your configuration.

Pass the JWT and create or retrieve the wallet

Flutter’s auth client is headless. Use your own auth provider to obtain the JWT, then pass it to client.auth.setJwt(jwt). The wallet controller auto-loads or creates a wallet when createOnLogin is configured.

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

// Whenever your auth provider produces (or refreshes) a JWT:
Future<void> syncCrossmintAuth(BuildContext context, String? jwt) async {
  final walletContext = CrossmintWalletContext.of(context);
  await walletContext.requireAuth.setJwt(jwt);

  // Optional — lookup or create a wallet once authenticated.
  if (jwt == null) return;
  final controller = walletContext.requireWalletController;
  final existing = await controller.getWallet(
    const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
  );
  if (existing == null) {
    await controller.createWallet(
      const CrossmintWalletCreateRequest(
        chain: 'base-sepolia',
        recovery: CrossmintEmailSignerConfig(email: 'YOUR_USER_EMAIL'),
      ),
    );
  }
}

See the Flutter SDK reference for details on setJwt and the auth client surface.

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Prerequisites

Using your own auth provider

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Documentation Index

​Prerequisites

​Using your own auth provider

Prerequisites

Using your own auth provider