Server-Side Rendering (SSR)

Integrate Crossmint Auth on the server-side for user authentication and management

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

Next.js (App Router)

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:

middleware.ts

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

export async function middleware(request: NextRequest) {
    // Skip middleware for API routes and static files
    if (request.nextUrl.pathname.startsWith("/api") || request.nextUrl.pathname.startsWith("/_next")) {
        return NextResponse.next();
    }

    const response = NextResponse.next();

    const jwt = request.cookies.get("crossmint-jwt")?.value;
    const refreshToken = request.cookies.get("crossmint-refresh-token")?.value;

    if (refreshToken == null) {
        return response;
    }

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

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

        // Only update response cookies if tokens have changed
        if (newJwt !== jwt || newRefreshToken.secret !== refreshToken) {
            response.cookies.set("crossmint-jwt", newJwt);
            response.cookies.set("crossmint-refresh-token", newRefreshToken.secret);
        }
    } catch (_) {
        // If auth fails, clear cookies and redirect to home
        response.cookies.delete("crossmint-jwt");
        response.cookies.delete("crossmint-refresh-token");
    }

    return response;
}

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.