Skip to main content
The headless checkout supports both server-side and client-side API keys. It’s important that you select the right key for your implementation.

​
When to use a server-side API key

  • Testing in the API Playground of the documentation
  • Testing with cURL requests or running scripts from your command line
  • Building applications that make API calls to your own backend, which then make the actual API call to Crossmint
The key consideration here is if the API request is coming from a server environment.

​
Server Side Example Code

route.ts (server-side)
import { callCrossmintAPI } from "@/app/utils/crossmint";
import { NextRequest, NextResponse } from "next/server";

const crossmintBaseUrl = process.env.CROSSMINT_API_URL;
const crossmintApiKey = process.env.CROSSMINT_API_KEY;

const crossmintAPIHeaders = {
    accept: "application/json",
    "content-type": "application/json",
    "x-api-key": crossmintApiKey,
};

const callCrossmintAPI = async (endpoint: string, options: { method: string; body?: any; params?: any }) => {
    const url = `${crossmintBaseUrl}/${endpoint}`;
    const { body, method } = options;

    const response = await fetch(url, {
        body: body ? JSON.stringify(body) : null,
        method,
        headers: crossmintAPIHeaders,
    });
    const json = await response.json();
    return json;
};

export async function POST(req: NextRequest, res: NextResponse) {
    try {
        const body = await req.json();
        console.log("create order: ", body);

        const apiResponse = await callCrossmintAPI("/orders", {
            method: "POST",
            body,
        });

        return NextResponse.json(apiResponse, { status: 200 });
    } catch (error) {
        console.log("failed to create order");
        return NextResponse.json({ message: "Error creating order" }, { status: 500 });
    }
}

​
When to use a client-side API key

  • Your application will be making API requests to Crossmint directly from a browser
When you create client-side API keys you must add the authorized origins that can use the key. For example, in testing you’ll need to indicate http://localhost:3000 (or similar local dev URLs) as authorized origins, or the request will be denied.
Client Key Domain There is one additional step when using a client-side API key in your application with headless checkout. The first call will be to create the order. The response will include a clientSecret property that you must persist in state and then pass as an additional header in subsequent API requests to the update-order or get-order routes.

​
Client Side Example Code

The sample code below shows direct client-side API calls to Crossmint using a client-side API key. The component.tsx file is simplified to only show the relevant logic for making requests directly from the browser to Crossmint’s API.
// note the end of try block where the clientSecret is saved to local state
const { setOrder, setClientSecret } = useLocalState();

const createOrder = async (orderInput: any) => {
    try {
        const res = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY,
            },
            body: JSON.stringify(orderInput),
        });

        const order = await res.json();

        setOrder(order.order);
        setClientSecret(order.clientSecret);
    } catch (e) {
        console.error(e);
        throw new Error("Failed to create order");
    }
};

​
Mobile Applications

When using client-side API keys in mobile applications, you must include an additional x-app-identifier header in your requests. This header should contain the bundle identifier (iOS) or package name (Android) that you whitelisted when creating your API key. Client Key Domain Mobile 
let headers = [
    "Content-Type": "application/json",
    "x-api-key": "your-client-side-api-key",
    "x-app-identifier": "com.yourcompany.yourapp", // iOS Bundle ID
    "authorization": clientSecret // When updating/reading orders
]
The x-app-identifier must match one of the mobile app identifiers you whitelisted when creating your client-side API key. For more information on setting up mobile app identifiers, see the Client-side API Keys documentation.
⌘I