Crossmint Auth (staging)

Crossmint Auth is designed for staging and moving fast. For production applications, Crossmint strongly recommends connecting your own authentication provider for full control over user management. See the Bring Your Own Auth guide.

Prerequisites

Staging project: Create a project in the Crossmint staging Console.
Client-side API key: Create a key with the users.create, users.read, and wallets.read scopes. In staging, all scopes are included by default.
Server-side API key: For the server examples, use a key with the users.read scope.

When to Use Crossmint Auth

Use Crossmint Auth for staging, demos, and prototypes. It supports email OTP, social sign-in with Google, Apple, or X, Farcaster, and external wallets. React web includes a login modal. React Native and Flutter use headless flows.

Setup

React
React Native
Flutter

Install the React SDK:

npm i @crossmint/client-sdk-react-ui

yarn add @crossmint/client-sdk-react-ui

pnpm add @crossmint/client-sdk-react-ui

bun add @crossmint/client-sdk-react-ui

Add CrossmintProvider and CrossmintAuthProvider to your app. Use useCrossmintAuth() to sign in and out.

Providers.tsx

"use client";

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

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

AuthButton.tsx

"use client";

import { useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

export function AuthButton() {
    const { login, logout, user } = useCrossmintAuth();

    return (
        <>
            {user == null ? (
                <button type="button" onClick={login}>Sign in</button>
            ) : (
                <button type="button" onClick={logout}>Sign out</button>
            )}
            <p>{user?.email}</p>
        </>
    );
}

Install the React Native SDK:

npx expo install @crossmint/client-sdk-react-native-ui expo-constants expo-device expo-secure-store expo-web-browser react-native-get-random-values react-native-svg react-native-webview

The SDK needs Expo SDK 58. npx expo install picks the versions of these packages that match your Expo SDK.The SDK uses expo-secure-store, expo-web-browser, and expo-device. OAuth also uses expo-linking, but the install command does not include it. Install it separately:

npx expo install expo-linking

Set a scheme in your Expo config for production builds. Expo Go uses a different redirect URI, which the SDK adjusts automatically.Add CrossmintProvider and CrossmintAuthProvider to your app:

Providers.tsx

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

export default function Providers({ children }: { children: React.ReactNode }) {
    return (
        <CrossmintProvider apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY!}>
            <CrossmintAuthProvider>{children}</CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

Use useCrossmintAuth() to start OAuth, handle its callback, and sign out:

AuthButton.tsx

import React, { useEffect } from "react";
import { Text, TouchableOpacity } from "react-native";
import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
import * as Linking from "expo-linking";

export function AuthButton() {
    const { loginWithOAuth, createAuthSession, logout } = useCrossmintAuth();
    const url = Linking.useURL();

    useEffect(() => {
        if (url != null) {
            createAuthSession(url);
        }
    }, [url, createAuthSession]);

    return (
        <>
            <TouchableOpacity onPress={() => loginWithOAuth("google")}>
                <Text>Sign in with Google</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={logout}>
                <Text>Sign out</Text>
            </TouchableOpacity>
        </>
    );
}

Install the Flutter SDK:

flutter pub add crossmint_flutter

# Add to your pubspec.yaml dependencies:
dependencies:
  crossmint_flutter: ^0.1.0

Initialize the client and restore the session when your app starts:

crossmint.dart

import 'package:crossmint_flutter/crossmint_client.dart';
import 'package:crossmint_flutter/crossmint_flutter_auth.dart';

final client = CrossmintClient(
  config: CrossmintClientConfig(
    apiKey: const String.fromEnvironment('CROSSMINT_API_KEY'),
    appScheme: 'myapp',
  ),
);

Future<void> initializeCrossmint() async {
  await client.initialize();
  await client.auth.restoreSession();
  final authRouter = CrossmintAuthCallbackRouter(auth: client.auth);
  await authRouter.start();
}

Register myapp as the OAuth callback scheme in Android and iOS.Add this intent filter to the main activity in android/app/src/main/AndroidManifest.xml:

android/app/src/main/AndroidManifest.xml

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" />
</intent-filter>

Add this URL scheme to ios/Runner/Info.plist:

ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

The client config above sets appScheme to myapp.Call loginWithOAuth to sign in and logout to sign out:

client.auth.loginWithOAuth(CrossmintOAuthProvider.google);
client.auth.logout();

For Swift and Kotlin, see the Crossmint Auth (OTP) tab in the Swift and Kotlin quickstarts.

Check That It Works

Start the React app, sign in, and confirm that your email appears. Set loginMethods on CrossmintAuthProvider to choose which methods appear. Email and Google are enabled by default.

Providers.tsx

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

export default function Providers({ children }: { children: React.ReactNode }) {
    return (
        <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY ?? ""}>
            <CrossmintAuthProvider loginMethods={["email", "google", "farcaster", "twitter", "web3"]}>
                {children}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

Supported methods include email OTP, social accounts, Farcaster, and external wallets. Use "web3:evm-only" or "web3:solana-only" to limit external wallet types. Set authModalTitle, termsOfServiceText, and appearance on CrossmintAuthProvider to customize the login modal.

import { CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

<CrossmintAuthProvider
    authModalTitle="Sign in to My App"
    termsOfServiceText={
        <p>
            By continuing, you agree to our <a href="/terms">Terms of Service</a> and{" "}
            <a href="/privacy">Privacy Policy</a>
        </p>
    }
    appearance={{
        spacingUnit: "8px",
        borderRadius: "12px",
        colors: {
            inputBackground: "#fffdf9",
            buttonBackground: "#fffaf2",
            border: "#835911",
            background: "#FAF5EC",
            textPrimary: "#5f2c1b",
            textSecondary: "#835911",
            textLink: "#1400cb",
            danger: "#ff3333",
            accent: "#602C1B",
        },
    }}
>
    {children}
</CrossmintAuthProvider>

Read the User Profile

Use useCrossmintAuth().user to read the signed-in user’s profile:

import { useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

export function UserProfile() {
    const { user } = useCrossmintAuth();
    return <p>{user?.email}</p>;
}

Verify Sessions on Your Server

Install @crossmint/server-sdk and create CrossmintAuth with a server-side API key that has the users.read scope. Use getSession to validate or refresh a session. Use verifyCrossmintJwt to verify a JWT:

session-route.ts

import express from "express";
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const app = express();
const crossmint = createCrossmint({
    apiKey: process.env.SERVER_CROSSMINT_API_KEY!,
});
const crossmintAuth = CrossmintAuth.from(crossmint);

app.get("/api/session", async (req, res) => {
    try {
        const { jwt: token, userId } = await crossmintAuth.getSession(req, res);
        await crossmintAuth.verifyCrossmintJwt(token);
        res.json({ userId });
    } catch {
        res.status(401).json({ error: "Unauthorized" });
    }
});

app.listen(3000);

See the TypeScript SDK reference for the full API.

Protect Session Tokens

By default, client-side JavaScript can access Crossmint Auth tokens. You can set secure cookie options for the refresh token. The session JWT remains available to client-side JavaScript because the client SDK needs it for API calls. Add refresh and logout routes to your server. The server stores the refresh token in an httpOnly cookie:

server.ts

import express from "express";
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const app = express();
const crossmint = createCrossmint({
    apiKey: process.env.SERVER_CROSSMINT_API_KEY!,
});
const crossmintAuth = CrossmintAuth.from(crossmint, {
    cookieOptions: {
        httpOnly: true,
        secure: true,
    },
});

app.post("/api/auth/refresh", async (req, res) => {
    await crossmintAuth.handleCustomRefresh(req, res);
    res.end();
});

app.post("/api/auth/logout", async (req, res) => {
    await crossmintAuth.logout(req, res);
    res.end();
});

app.listen(3000);

Point CrossmintAuthProvider to these routes:

Providers.tsx

import type { ReactNode } from "react";
import {
    CrossmintAuthProvider,
    CrossmintProvider,
} from "@crossmint/client-sdk-react-ui";

export function Providers({ children }: { children: ReactNode }) {
    return (
        <CrossmintProvider
            apiKey={process.env.NEXT_PUBLIC_CLIENT_CROSSMINT_API_KEY!}
        >
            <CrossmintAuthProvider
                refreshRoute="/api/auth/refresh"
                logoutRoute="/api/auth/logout"
            >
                {children}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

User Webhooks

Crossmint sends the users.created event when a user signs up with Crossmint Auth. The id field identifies the user. The email and phoneNumber fields appear when the user signs up with the matching method.

{
    "type": "users.created",
    "status": "success",
    "data": {
        "id": "123",
        "email": "test@test.com",
        "phoneNumber": "123456789"
    }
}

Return a quick 2xx response to confirm delivery.

Move to Production

For production, connect your own auth provider with the Bring Your Own Auth guide. Then configure JWT Authentication in the Crossmint Console.

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Prerequisites

When to Use Crossmint Auth

Setup

Check That It Works

Read the User Profile

Verify Sessions on Your Server

Protect Session Tokens

User Webhooks

Move to Production

Next Steps

Use Your Own Auth Provider

JWT Authentication

React Wallet Quickstart

Crossmint Auth TypeScript SDK

​Prerequisites

​When to Use Crossmint Auth

​Setup

​Check That It Works

​Login Methods

​Customize the Login Modal

​Read the User Profile

​Verify Sessions on Your Server

​Protect Session Tokens

​User Webhooks

​Move to Production

​Next Steps

Use Your Own Auth Provider

JWT Authentication

React Wallet Quickstart

Crossmint Auth TypeScript SDK

Prerequisites

When to Use Crossmint Auth

Setup

Check That It Works

Login Methods

Customize the Login Modal

Read the User Profile

Verify Sessions on Your Server

Protect Session Tokens

User Webhooks

Move to Production

Next Steps