Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the first two steps of the cards flow: authenticating a user to obtain a JWT, then registering an agent that can pay on their behalf. By the end you will have an agentId to use in every subsequent step.

​
Prerequisites

​
Step 1: Authenticate the User

Before calling any Crossmint endpoint you need a valid session JWT for the user. How you obtain it depends on your auth provider. Below is the pattern used by the quickstart with Stytch: 
import { useStytch } from "@stytch/nextjs";
import { useCrossmint } from "@crossmint/client-sdk-react-ui";

function useAuthSetup() {
    const stytch = useStytch();
    const { setJwt } = useCrossmint();

    // After the user completes login (e.g. Google OAuth redirect):
    const tokens = stytch.session.getTokens();
    const jwt = tokens?.session_jwt ?? "";

    // Bridge the JWT to the Crossmint SDK so it can authenticate requests
    setJwt(jwt);

    return jwt;
}
The key requirement is that every Crossmint API call includes:
  • X-API-KEY header with your Crossmint client API key
  • Authorization: Bearer <jwt> header with the user’s session JWT
If you are using a different auth provider, replace the Stytch calls above with your provider’s equivalent. See Identity and Auth for more options.

​
Step 2: Register an Agent

With the JWT in hand, send a POST request to /api/unstable/agents to create an agent for this user. 
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(`${BASE_URL}/agents`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        metadata: {
            name: "Card Payment Agent",
            description: "Default agent for card payments",
        },
    }),
});

const agent = await response.json();
console.log(agent.agentId); // e.g. "d290f1ee-6c54-4b01-90e6-d701748f0851"
Store the agentId — you will pass it when saving cards, setting up card permissions, and fetching secure card numbers. You typically create one agent per user. For the full request and response schema, see the Create Agent API Reference. 
{
  "agentId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "metadata": {
    "name": "Card Payment Agent",
    "description": "Default agent for card payments"
  }
}

​
What Is Next

Now that you have an authenticated user and a registered agent, the next step is to Save a Card so the agent can be given permission to pay with it.