Server-Side Rendering (SSR)

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.

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 i @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:

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

Next.js (App Router)
Express.js
Vanilla Node.js

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 { 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;
}

For Express.js applications, you can create middleware to handle authentication:

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);

const authMiddleware = async (req, res, next) => {
  try {
    const { jwt, refreshToken, userId } = await crossmintAuth.getSession(req, res);
    req.user = { userId };
    next();
  } catch (error) {
    res.status(401).json({ error: "Authentication failed" });
  }
};

app.use(authMiddleware);

app.get("/protected", (req, res) => {
  res.json({ message: "Protected route", userId: req.user.userId });
});

For a basic Node.js server:

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

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

const server = http.createServer(async (req, res) => {
  if (req.url === "/protected") {
    try {
      const { userId } = await crossmintAuth.getSession(req, res);
      const userData = await crossmintAuth.getUser(userId);

      res.writeHead(200, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ message: "Authenticated", user: userData }));
    } catch (error) {
      res.writeHead(401, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ error: "Authentication failed" }));
    }
  } else {
    res.writeHead(404);
    res.end();
  }
});

server.listen(3000);

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., Twitter, 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.

Introduction

User Identity

User Authentication

Server-Side Rendering (SSR)

Overview

Installation

Initialization

Core Functionality

Session Management

User Profile Retrieval

JWT Verification

Introduction

User Identity

User Authentication

Documentation Index

​Overview

​Installation

​Initialization

​Core Functionality

​Session Management

​User Profile Retrieval

​JWT Verification

Overview

Installation

Initialization

Core Functionality

Session Management

User Profile Retrieval

JWT Verification