Skip to main content

CrossmintAuth

The CrossmintAuthServer class (exported as CrossmintAuth) provides server-side authentication functionality for managing user sessions, handling token refresh, and cookie management.

Installation

npm install @crossmint/server-sdk

Initialization

import { CrossmintAuth } from '@crossmint/server-sdk';
import { Crossmint } from '@crossmint/common-sdk-base';

const crossmint = new Crossmint({
  apiKey: process.env.CROSSMINT_API_KEY
});

const auth = CrossmintAuth.from(crossmint, {
  refreshRoute: '/api/auth/refresh',
  cookieOptions: {
    httpOnly: true,
    secure: true,
    sameSite: 'Lax'
  }
});

Constructor options

crossmint
Crossmint
required
Crossmint SDK instance initialized with your API key.
options
CrossmintAuthServerOptions
Configuration options for the authentication instance.

Static methods

from()

Creates a new CrossmintAuth instance.
const auth = CrossmintAuth.from(crossmint, options);
crossmint
Crossmint
required
Crossmint SDK instance.
options
CrossmintAuthServerOptions
Configuration options.
Returns: CrossmintAuthServer

Instance methods

See Session Methods for detailed documentation of getSession(), logout(), and handleCustomRefresh().

getJwksUri()

Returns the JWKS URI for JWT verification.
const jwksUri = auth.getJwksUri();
Returns: string - The JWKS URI endpoint.

verifyCrossmintJwt()

Verifies a Crossmint JWT token.
const decoded = await auth.verifyCrossmintJwt(token, jwks);
token
string
required
The JWT token to verify.
jwks
JSONWebKeySet
Optional JWKS for verification. If not provided, fetches from the JWKS URI.
Returns: Promise<JWTPayload> - The decoded and verified JWT payload.

storeAuthMaterial()

Stores authentication material in cookies.
auth.storeAuthMaterial(response, authMaterial);
response
GenericResponse
required
The HTTP response object (Node.js ServerResponse or Web API Response).
authMaterial
AuthMaterial
required
Authentication material containing JWT and refresh token.

getUser()

Retrieves user information by external user ID.
const user = await auth.getUser(externalUserId);
externalUserId
string
required
The external user ID to look up.
Returns: Promise<SDKExternalUser> - The user object.

Type definitions

GenericRequest

Accepts either Node.js IncomingMessage or Web API Request objects.
type GenericRequest = IncomingMessage | Request;

GenericResponse

Accepts either Node.js ServerResponse or Web API Response objects.
type GenericResponse = ServerResponse | Response;

AuthMaterial

type AuthMaterial = {
  jwt: string;
  refreshToken: RefreshToken;
};

type RefreshToken = {
  secret: string;
  expiresAt: string;
};

AuthMaterialBasic

type AuthMaterialBasic = {
  jwt?: string;
  refreshToken: string;
};

AuthSession

type AuthSession = {
  jwt: string;
  refreshToken: RefreshToken;
  userId: string;
};

Error handling

All methods may throw CrossmintAuthenticationError when authentication fails.
try {
  const session = await auth.getSession(request, response);
} catch (error) {
  if (error instanceof CrossmintAuthenticationError) {
    console.error('Authentication failed:', error.message);
  }
}

Build docs developers (and LLMs) love