The Crossmint Server SDK provides flexible authentication methods that work across different server-side frameworks.
Initializing CrossmintAuth
Before authenticating users, initialize the CrossmintAuth class:
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";
const crossmint = createCrossmint({
apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
});
const crossmintAuth = CrossmintAuth.from(crossmint);
Store your API key in environment variables and never commit it to version control.
Getting User Sessions
The getSession() method validates JWT tokens and automatically refreshes them when expired.
Next.js App Router
In Next.js, fetch cookies and pass them to the getSession method:
import { cookies } from "next/headers";
const cookieStore = cookies();
const jwtCookie = cookieStore.get("crossmint-session")?.value;
const refreshCookie = cookieStore.get("crossmint-refresh-token")?.value;
const { jwt, userId } = await crossmintAuth.getSession({
jwt: jwtCookie,
refreshToken: refreshCookie,
});
README.md:38
Express and Other Frameworks
For frameworks with access to the request object, pass it directly:
const { jwt, userId } = await crossmintAuth.getSession(request);
README.md:34
Storing Authentication Material
Automatic Cookie Storage
For frameworks with access to the response object, pass it to getSession() to automatically store authentication material in cookies:
const { jwt, userId } = await crossmintAuth.getSession(request, response);
README.md:57
Manual Cookie Storage
You can also manually store authentication material using the storeAuthMaterial() method:
const authMaterial = {
jwt: "your-jwt-token",
refreshToken: {
secret: "your-refresh-token",
expiresAt: "2024-12-31T23:59:59Z"
}
};
crossmintAuth.storeAuthMaterial(response, authMaterial);
CrossmintAuthServer.ts:137
Fetch detailed user information using the external user ID:
const user = await crossmintAuth.getUser(userId);
CrossmintAuthServer.ts:68
Verifying JWT Tokens
Manually verify JWT tokens using the verifyCrossmintJwt() method:
const decodedToken = await crossmintAuth.verifyCrossmintJwt(jwt);
const decodedToken = await crossmintAuth.verifyCrossmintJwt(jwt, customJwks);
CrossmintAuthServer.ts:130
Error Handling
The SDK throws CrossmintAuthenticationError when authentication fails:
try {
const { jwt, userId } = await crossmintAuth.getSession(request, response);
// Authentication successful
} catch (error) {
if (error instanceof CrossmintAuthenticationError) {
// Handle authentication error
console.error("Authentication failed:", error.message);
}
}
Always handle authentication errors gracefully to provide a good user experience. The SDK automatically clears cookies when authentication fails.
Complete Example
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";
import { cookies } from "next/headers";
import { NextRequest, NextResponse } from "next/server";
const crossmint = createCrossmint({
apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
});
const crossmintAuth = CrossmintAuth.from(crossmint);
export async function GET(request: NextRequest) {
try {
const cookieStore = cookies();
const jwtCookie = cookieStore.get("crossmint-session")?.value;
const refreshCookie = cookieStore.get("crossmint-refresh-token")?.value;
const { jwt, userId } = await crossmintAuth.getSession({
jwt: jwtCookie,
refreshToken: refreshCookie,
});
const user = await crossmintAuth.getUser(userId);
return NextResponse.json({ user });
} catch (error) {
return NextResponse.json(
{ error: "Authentication failed" },
{ status: 401 }
);
}
}
Next Steps
Session Management
Learn how to handle session validation and token refresh