Creates a secure, short-lived Credential Vault session for a merchant and returns a hosted URL. Embed the URL in your web application (or share it as a link) so the customer can store their merchant login securely — the credentials never pass through your backend.

How it Works

Some merchants require the customer to be logged in before an order can be placed. Calling POST /credentials/session provisions a time-limited vault session tied to a specific customer email and merchant pair. The flow is:

1. Your backend calls this endpoint with the merchant's domain and the customer's email.
2. CartAI returns an iframeUrl and an expiresIn value (in minutes).
3. You embed the URL in an iframe or send it to the customer or admin as a link.
4. They enter their merchant login on CartAI's hosted page. The credentials are stored in the vault against the email and merchant pair.
5. When you create a checkout task for the same email and merchant with options.useSavedCredentialToLogin set to true, CartAI's agent uses the saved credentials to sign in during checkout.

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

To get your API key, generate it from the CartAI Admin Portal after your account is provisioned. Contact the CartAI Account Management Team to request access.

Request Body

Full Request Example

curl --location 'https://api.cartai.ai/credentials/session' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "merchantDomain": "https://saltiebeauty.com",
      "email": "[email protected]"
  }'

Response

A successful request returns HTTP 200 with the following body.

{
  "status": "success",
  "message": "Credential vault session created successfully",
  "data": {
    "iframeUrl": "https://credshield.cartai.ai?token=<jwt_token>&merchant=saltiebeauty.com",
    "expiresIn": 10
  }
}

Response Fields

Embedding the Vault URL

The iframeUrl is designed to be embedded directly in your web application so the user stays on your page while they enter their credentials.

<iframe
  id="credential-frame"
  src="IFRAME_URL"
  width="480"
  height="640"
  style="border: none;"
  title="CartAI Credential Vault"
></iframe>

// Dynamically set the src after creating the session
document.getElementById('credential-frame').src = sessionData.data.iframeUrl;

Alternatively, send the URL by email, chat, or your admin console so the user can open it directly — for example, when an admin is setting up a shared business account rather than a shopper saving their own login.

Using the Saved Credentials at Checkout

Once the user has saved their credentials, create a checkout task with options.useSavedCredentialToLogin set to true, the same email in customer.contact.email, and a product URL on the same merchant domain. CartAI looks up the credentials saved for that email and merchant pair and uses them to log in during checkout.

If the email or merchant domain doesn't match, CartAI can't find the saved credentials. See the Credential Vault guide for the full end-to-end flow.

Error Reference