Skip to main content

​
Configuration

The Server SDK provides configuration options for customizing authentication behavior, cookie settings, and token refresh routes.

​
CrossmintAuthServerOptions

Configuration object passed to CrossmintAuth.from(). 
type CrossmintAuthServerOptions = {
  refreshRoute?: string;
  cookieOptions?: CookieOptions;
};

​
refreshRoute

​
refreshRoute
string
Custom route for token refresh. When set, the SDK uses your custom endpoint instead of the default Crossmint refresh endpoint.
Default: null (uses Crossmint’s default refresh endpoint)

​
Example

const auth = CrossmintAuth.from(crossmint, {
  refreshRoute: '/api/auth/refresh'
});
When using a custom refresh route, your endpoint should:
  1. Accept POST requests with a refresh token
  2. Call the Crossmint refresh endpoint or handle token refresh
  3. Return refreshed authentication material

​
cookieOptions

​
cookieOptions
CookieOptions
Configuration for authentication cookies. Controls security, expiration, and domain settings.
Default: {} (uses secure defaults)

​
CookieOptions

Configuration for HTTP cookies used to store authentication tokens. 
type CookieOptions = {
  expiresAt?: string;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: 'Lax' | 'Strict' | 'None';
  domain?: string;
};

​
expiresAt

​
expiresAt
string
ISO 8601 timestamp for cookie expiration. If not provided, uses the refresh token’s expiration time.
Default: Matches refresh token expiration Example: 
cookieOptions: {
  expiresAt: '2024-12-31T23:59:59Z'
}

​
httpOnly

​
httpOnly
boolean
When true, prevents JavaScript access to cookies. Recommended for security.
Default: true (recommended) Example: 
cookieOptions: {
  httpOnly: true
}
Setting httpOnly: false exposes tokens to XSS attacks. Only disable this if you have a specific requirement and understand the security implications.

​
secure

​
secure
boolean
When true, cookies are only sent over HTTPS connections.
Default: false Example: 
cookieOptions: {
  secure: true
}
Always set secure: true in production environments. Set to false only for local development over HTTP.

​
sameSite

​
sameSite
'Lax' | 'Strict' | 'None'
Controls when cookies are sent with cross-site requests.
  • Lax: Cookies sent with top-level navigation and same-site requests (recommended)
  • Strict: Cookies only sent with same-site requests
  • None: Cookies sent with all requests (requires secure: true)
Default: Lax Example: 
cookieOptions: {
  sameSite: 'Lax'
}
Use sameSite: 'Lax' for most applications. Use sameSite: 'None' only if you need to support cross-origin requests and ensure secure: true is set.

​
domain

​
domain
string
Domain for which the cookie is valid. Allows cookies to be shared across subdomains.
Default: Current domain only Example: 
cookieOptions: {
  domain: '.example.com' // Shares cookies across *.example.com
}
Include the leading dot (.example.com) to make cookies available to all subdomains.

​
Complete configuration example

​
Production configuration

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',
    domain: '.example.com'
  }
});

​
Development configuration

const auth = CrossmintAuth.from(crossmint, {
  cookieOptions: {
    httpOnly: true,
    secure: false, // Allow HTTP for local development
    sameSite: 'Lax'
  }
});

​
Minimal configuration

// Uses secure defaults
const auth = CrossmintAuth.from(crossmint);
The SDK stores authentication material in the following cookies:
  • crossmint_jwt - JWT access token
  • crossmint_refresh_token - Refresh token
These cookie names are managed automatically by the SDK.

​
Security best practices

Set httpOnly: true to prevent JavaScript access and protect against XSS attacks.
cookieOptions: {
  httpOnly: true
}
Set secure: true in production to ensure cookies are only sent over HTTPS.
cookieOptions: {
  secure: process.env.NODE_ENV === 'production'
}
Use sameSite: 'Lax' for most applications, or sameSite: 'Strict' for maximum security.
cookieOptions: {
  sameSite: 'Lax'
}

​
Runtime compatibility

The Server SDK works with both Node.js and Web API environments:
  • Node.js: Express, Fastify, Next.js API routes (Pages Router)
  • Web API: Next.js App Router, Vercel Edge Functions, Cloudflare Workers
The SDK automatically detects the runtime and uses the appropriate request/response adapters. 
// Works in both Node.js and Edge runtimes
export async function GET(request) {
  const session = await auth.getSession(request);
  return Response.json({ userId: session.userId });
}

Build docs developers (and LLMs) love

Get started for freeTalk to us