Crossmint Auth provides a flexible and simple authentication solution for your crypto server-side applications. This guide covers how to integrate and use Crossmint Auth across various server-side frameworks.

​
Overview

Our server SDK allows you to:

  • Manage user sessions
  • Retrieve user profiles
  • Verify JSON Web Tokens (JWTs)

​
Installation

First, install the Crossmint Server SDK:

npm install @crossmint/server-sdk

​
Initialization

To use Crossmint Auth, you need to initialize it with your Server API key. This API requires the users.read scope.

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

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

​
Core Functionality

​
Session Management

The getSession method validates or refreshes a user’s session based on their JWT and refresh token.

const { jwt, refreshToken, userId } = await crossmintAuth.getSession(req, res);

This method:

  1. Fetches the current JWT and refresh token from the cookies with keys crossmint-jwt and crossmint-refresh-token.
  2. Checks if the current JWT is valid
  3. Refreshes the session if needed
  4. Stores the new JWT and refresh token in cookies
  5. Returns new auth materials and the user ID

For other frameworks that do not expose standard request and response objects, such as Next.js using the App Router, you can pass in an object with jwt and refreshToken properties instead:

import { cookies } from "next/headers";

export default async function ProtectedRoute() {
  const cookieStore = cookies();
  const jwt = cookieStore.get("crossmint-jwt")?.value;
  const refreshToken = cookieStore.get("crossmint-refresh-token")?.value;

  if (refreshToken) {
    try {
      const { jwt: newJwt, refreshToken: newRefreshToken, userId } = await crossmintAuth.getSession({
        jwt,
        refreshToken,
      });

      // Update cookies with new tokens
      cookies().set("crossmint-jwt", newJwt);
      cookies().set("crossmint-refresh-token", newRefreshToken.secret);

      // Fetch user data or perform authorized actions
      const userData = await crossmintAuth.getUser(userId);

      return <div>Welcome, {userData.email}!</div>;
    } catch (error) {
      // Handle authentication error
      return <div>Authentication failed. Please log in again.</div>;
    }
  }

  // Handle unauthenticated state
  return <div>Please log in to access this page.</div>;
}

​
User Profile Retrieval

Fetch user details using the getUser method:

const user = await crossmintAuth.getUser(userId);

This provides access to user information such as email, phone number, and connected accounts (e.g., Google, Farcaster).

​
JWT Verification

Verify JWTs independently using the verifyCrossmintJwt method:

const decodedJwt = crossmintAuth.verifyCrossmintJwt(token);

This is useful for validating tokens in middleware or specific endpoints. We expose our public keys for this purpose at https://www.crossmint.com/.well-known/jwks.json.

CustomizationUser Webhooks