Credentials

Some merchants require the customer to be logged in to their account before an order can be placed. CartAI's Credential Vault lets your customer (or an admin) store their merchant login securely through a hosted UI, so the checkout agent can sign in on their behalf. The credentials never pass through your backend.

How It Works

1. Create a secure vault session with the Create Credential Vault Session API.
2. CartAI returns an iframeUrl.
3. Send the iframeUrl to the customer or admin, depending on your use case.
4. They enter their merchant login on CartAI's hosted page.
5. Create a checkout task with options.useSavedCredentialToLogin set to true. CartAI uses the credentials saved for that email and merchant combination.

Step 1 — Create a Credential Vault Session

Call POST /credentials/session from your backend with the merchant's domain and the customer's email.

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]"
  }'

Request Fields

Step 2 — Receive the iframeUrl

Response:

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

Step 3 — Send the iframeUrl to the Customer or Admin

Who fills in the credentials depends on your use case. For example, a shopper saving their own account, or an admin setting up a shared business account. Deliver the URL in whichever way fits your application:

Embed in an iframe — keep the user 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;

Share a link — send the URL by email, chat, or your admin console so the user can open it directly.

Step 4 — The User Saves Their Credentials

The user enters their merchant login on CartAI's hosted page. The credentials are stored in the vault against the email and merchant pair from Step 1. No credential data touches your servers.

Step 5 — Use the Saved Credentials in Create Checkout

When you create a checkout task, set options.useSavedCredentialToLogin to true. CartAI finds the credentials saved for the customer's email and the merchant, and uses them to log in during checkout.

{
  "customer": {
    "contact": {
      "email": "[email protected]"
    }
  },
  "tasks": [
    {
      "url": "https://saltiebeauty.com/products/example-product",
      "quantity": 1
    }
  ],
  "options": {
    "useSavedCredentialToLogin": true
  }
}