Sign In to Stores

Some purchases need the user’s account at the merchant: for saved addresses, member prices, order history, a cart, or a subscription. A browser profile keeps the user signed in. The user signs in during one checkout, and later checkouts start signed in. The user signs in through the checkout’s questions. Collect the password with CrossmintProtectedInput. See Answer Questions. The password collection is separate from the saved session.

Prerequisites

Agent Checkout integration: Complete the Agent Checkouts quickstart so that your app can start a checkout, follow it, and send answers.
Server-side API key: Use a production key with agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.browser-profiles.create scopes.
Client-side API key: To show the password field, CrossmintProtectedInput needs a production client-side key with the protected-inputs.create scope, and the signed-in user’s JWT. See Answer Questions.

Browser profiles are scoped to a user. With a server-side key, identify that user with x-crossmint-user-id on every request.

Always send x-crossmint-user-id with a server-side key. Without it, requests use your project’s shared service subject, so different users could share the same browser profile.

const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";

const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};

Create a browser profile for the user

Create one profile and store its id with the user in your system. The optional label is only for your own bookkeeping.

curl --request POST \
    --url https://www.crossmint.com/api/unstable/agent-checkouts/browser-profiles \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --header 'x-crossmint-user-id: YOUR_USER_ID' \
    --data '{ "label": "Primary shopping profile" }'

// Uses BASE_URL and headers from the prerequisites.
const res = await fetch(`${BASE_URL}/browser-profiles`, {
    method: "POST",
    headers,
    body: JSON.stringify({ label: "Primary shopping profile" }),
});

if (!res.ok) {
    throw new Error(`Could not create browser profile: ${res.status}`);
}
const { id: profileId } = await res.json();

import os

import requests

response = requests.post(
    "https://www.crossmint.com/api/unstable/agent-checkouts/browser-profiles",
    headers={
        "X-API-KEY": os.environ["CROSSMINT_SERVER_API_KEY"],
        "x-crossmint-user-id": "YOUR_USER_ID",
    },
    json={"label": "Primary shopping profile"},
)
response.raise_for_status()
profile_id = response.json()["id"]

The response contains metadata only. It does not return cookies, tokens, or other browser state.

{
    "id": "7c3b1f2a-9d54-4e80-b1a6-2f0c8e5d4a31",
    "label": "Primary shopping profile",
    "createdAt": "2026-08-10T11:00:00.000Z",
    "updatedAt": "2026-08-10T11:00:00.000Z"
}

A user can have one browser profile. Reuse that profile rather than creating one for each merchant.

Attach the profile to a checkout

Pass the profile as browser.profileId when you start a checkout. The first checkout starts without a saved session, so tell the checkout to sign in before it buys.

// Uses BASE_URL, headers, and profileId from the earlier steps.
const res = await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
        request: {
            startUrl: "https://shop.example.com/products/classic-tee",
            task: "Sign in, then buy the medium in black.",
        },
        browser: { profileId },
        constraints: {
            maxCost: { amount: "100.00", currency: "USD" },
        },
    }),
});

if (!res.ok) {
    throw new Error(`Could not start checkout: ${res.status}`);
}
const { runId } = await res.json();

You can also include browser.location in the same object when the checkout must connect from a different country. See Configure a Checkout.Follow the checkout and answer the sign-in questions. See Answer Questions. An accepted answer does not confirm that the sign-in succeeded.

Complete the first signed-in checkout

Answer each question by its requestId, and keep following the checkout. After the checkout ends without an error, the merchant’s session is stored in the browser profile.The profile does not report what happened during a checkout. Read the checkout and its messages to confirm whether the agent signed in, encountered another verification step, or completed the purchase.

Reuse the profile on later checkouts

Pass the same browser.profileId on the next checkout for this user.

// Uses BASE_URL, headers, and profileId from the earlier steps.
const nextResponse = await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
        request: {
            startUrl: "https://shop.example.com/products/wool-scarf",
            task: "Buy one in grey using my saved account.",
        },
        browser: { profileId },
        constraints: {
            maxCost: { amount: "100.00", currency: "USD" },
        },
    }),
});
if (!nextResponse.ok) {
    throw new Error(`Could not start checkout: ${nextResponse.status}`);
}

The checkout loads the saved session before it opens the merchant. If the merchant has expired the session or requires the user to sign in again, the checkout asks new questions. Answer them as in the first checkout.

How Browser Profiles Stay Protected

The profile API returns metadata only. Cookies, tokens, and other saved browser state are not returned.
Saved browser state is not added to a model prompt. It is loaded only into the browser for that user’s checkout.
Each checkout has its own browser. Crossmint closes the browser when the checkout ends.
Payment is separate. See Pay for a Checkout for the payment step.

Manage a Browser Profile

Browser profile routes live under https://www.crossmint.com/api/unstable/agent-checkouts/browser-profiles and are documented with the Agent Checkouts API reference.

A user can have one profile. Creating another returns 409.
Requesting a profile owned by another user returns 404, so its existence cannot be probed.
label is the only editable field.
Deleting a profile irreversibly erases its saved browser state. Checkouts that already use it continue, and the erasure finishes after they end.

Next Steps

Pay for a Checkout

Pay with an order intent, a card saved at the merchant, or another method

Manage a Store Cart

Keep a cart at the merchant, and check out later

Create a Browser Profile

Review the complete browser profile request

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Prerequisites

How Browser Profiles Stay Protected

Manage a Browser Profile

Next Steps

Pay for a Checkout

Manage a Store Cart

Create a Browser Profile

​Prerequisites

​Sign In Once and Reuse the Session

​How Browser Profiles Stay Protected

​Manage a Browser Profile

​Next Steps

Pay for a Checkout

Manage a Store Cart

Create a Browser Profile

Prerequisites

Sign In Once and Reuse the Session

How Browser Profiles Stay Protected

Manage a Browser Profile

Next Steps