Buy from Authenticated Stores

Let a user sign in once, reuse the merchant session on later checkouts, and submit passwords securely

Some purchases require a merchant account for saved addresses, member prices, order history, or a cart the user already filled. A browser profile lets Agent Checkouts save the merchant session after the user signs in and load it on later runs.

Passwords are separate from the saved session. When a merchant requires one, Agent Checkouts sends a typed protected input request. The user enters the password in a Crossmint-hosted field, and your agent runtime sends back only the resulting ID.

This works with any user channel. A web app can render the password field inline, a native app can open a webview, and a messaging or voice agent can send the user to an authenticated page in your application.

Prerequisites

• Agent Checkout integration: Complete the Agent Checkouts quickstart so your application can start a run, observe it, and send messages.
• 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: Add protected-inputs.create to the key used on the page that collects a password. Add protected-inputs.read if your integration lists protected inputs and protected-inputs.revoke if it revokes them. In staging, all scopes are included by default.
• User authentication: Authenticate that page with a user JWT for the same user as the checkout run. See Crossmint Auth or configure an external identity provider.
• Secure React surface: Use a page in your application where you can render CrossmintProtectedInput.

Browser profiles and protected inputs 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": CROSSMINT_SERVER_API_KEY,
    "x-crossmint-user-id": "YOUR_USER_ID",
};

Sign In Once and Reuse the Session

1. 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.

   Node.js

   const res = await fetch(`${BASE_URL}/browser-profiles`, {
       method: "POST",
       headers,
       body: JSON.stringify({ label: "Primary shopping profile" }),
   });
   
   const { id: profileId } = await res.json();
   

   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.

2. Attach the profile to a checkout run

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

   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" },
           },
       }),
   });
   
   const { runId } = await res.json();
   

   You can also include browser.location in the same object when the checkout should run from a particular country. See Set the Browser Location.

   Observe the run as described in the quickstart. The agent can request an email or username with a normal form request. It requests a password with a protected input request, which you handle in Submit a Password Securely.

3. Complete the first signed-in checkout

   Answer each request by its requestId, then continue observing the run. After the checkout finishes cleanly, the merchant’s session is stored in the browser profile.

   The profile itself does not report what happened during a checkout. Read the run and its messages to confirm whether the agent signed in, encountered another verification step, or completed the purchase.

4. Reuse the profile on later runs

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

   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" },
           },
       }),
   });
   

   The run loads the saved session before it navigates. If the merchant has expired the session or requires the user to sign in again, the agent sends new input requests. Handle them the same way as the first run.

Submit a Password Securely

1. Detect the protected input request

   The run moves to awaiting_input and exposes the request as requiredAction.request when you read the run and as an input_request part when you list or stream messages.

   Dispatch on interaction.kind === "protected". The request contains safe metadata about the credential and merchant, never the password itself.

   {
       "requestId": "req_456",
       "question": "Enter your password for shop.example.com to sign in.",
       "expiresAt": "2026-09-24T10:30:00.000Z",
       "interaction": {
           "kind": "protected",
           "purpose": "password",
           "merchant": { "domain": "shop.example.com" }
       }
   }
   

   • purpose is the kind of protected value requested. Today it is always "password".
   • merchant.domain is the merchant where the password may be used. Agent Checkouts can use it on this domain or its subdomains.

   The username or email is not part of this request. Supply it separately through a form response, the initial task, or a text message.

2. Send the user to a secure input surface

   Choose the handoff that fits your integration:

   Integration	Recommended handoff
   Web application	Render the protected input component inline.
   Native application	Open an authenticated webview or secure page in your app.
   Messaging or voice agent	Send an authenticated link or deep link to a page in your app. Resume the conversation after the page returns the ID.

   Associate the page with the run and requestId in your own application state. The user’s JWT, checkout run, and protected input must all represent the same user.

   If you cannot provide a secure interactive surface, ask the agent to use a guest checkout with action: "alternative", or refuse the request with action: "decline". Never ask the user to send a password in chat.

3. Collect the password

   Render CrossmintProtectedInput from @crossmint/client-sdk-react-ui. Build merchantUrl from the request’s merchant.domain, and keep the protectedInputId returned by onCreated.

   npm

   npm i @crossmint/client-sdk-react-ui
   

   import { CrossmintProtectedInput } from "@crossmint/client-sdk-react-ui";
   
   function PasswordRequest({ jwt, request, onProtectedInputId }) {
       const domain = request.interaction.merchant.domain;
   
       return (
           <CrossmintProtectedInput
               jwt={jwt}
               merchantUrl={`https://${domain}`}
               label={`Password for ${domain}`}
               onCreated={({ protectedInputId }) => onProtectedInputId(protectedInputId)}
               onError={({ code, message }) => console.error(code, message)}
           />
       );
   }
   

   See CrossmintProtectedInput in the React SDK reference under Agents → API Reference → React SDK → Components for all props and onError codes.

4. Submit the protected input ID

   Send one input_response part that references the request’s requestId. The message contains the ID, not the password.

   {
       "id": "msg_9d2e4b",
       "parts": [
           {
               "type": "input_response",
               "requestId": "req_456",
               "action": "submit",
               "response": {
                   "kind": "protected",
                   "protectedInputId": "5f0c2a9e-7b1d-4c3a-9e8f-2d6b4a1c0e7f"
               }
           }
       ]
   }
   

   The accepted response resumes the run. Continue observing it until it completes, asks for another input, or stops.

   Answer before the request’s expiresAt. If it expires, collect the password again for the new request.

   Never send a password in form values, the task, or a text message. Those values can enter the message history, and Agent Checkouts does not use them to fill password fields.

Protected Input Requirements

• Same project and user — render the component with the same Crossmint project, environment, and signed-in user as the checkout run.
• Matching merchant — build merchantUrl from the request’s merchant.domain.
• Enough lifetime — the protected input must remain valid until the checkout finishes. It lasts 24 hours by default and at most 7 days. Set expiresAt to the shortest practical duration.

How the Password Stays Protected

• The password does not reach your application code. The user types into a field hosted by Crossmint. Your page receives only the protectedInputId.
• Sensitive response data is sealed. After Crossmint accepts the response, subsequent run and message reads report that protected input was provided and whether it was applied. They do not return the password or ID to the model or message history.
• The agent cannot read the password. It fills and submits the merchant’s password field in one operation, then clears the field.
• The password is merchant-bound. A password collected for shop.example.com can be released on that domain or a subdomain such as accounts.shop.example.com, never an unrelated domain.

Recover from a Failed Sign-In

If Agent Checkouts cannot use the protected input, it retries when safe or sends a new protected input request. Answer the new requestId; do not reuse a response from an earlier request.

Code	Cause	What to do
protected_input_not_found	No protected input with this ID exists for the run’s environment, project, and user.	Render the component in the same environment and project, for the same user as the run.
protected_input_expired, protected_input_revoked	The protected input is no longer available.	Collect the password again, with a later expiresAt if needed.
merchant_mismatch	The sign-in page is not on the domain where the password may be used.	Build merchantUrl from the request’s merchant.domain.
provider_error, provider_unavailable	Crossmint could not release the password.	Let the agent retry. If it asks again, answer the new request. Contact support if the error persists.

When the merchant rejects the password, Agent Checkouts does not submit the same password again. It sends a new protected input request.

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 run has its own browser. The browser is released when the run finishes.
• Card details are not stored in a browser profile. Use a payment method described in Choose a Payment Method.

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. Runs already using it continue, and erasure finishes after they end.

Next Steps

Choose a Payment Method

Pay with an Agent Card, a merchant-saved card, or a local method

Provide Purchase Context

Give the checkout task more context and steer it while it runs