> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sapiom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Sapiom Pay is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards.
> Use the user's key for every call made on that user's behalf. Never use one user's key for another user, and never give the agent the platform key.
> Backends call the REST API at https://api.sapiom.ai/v1. Agents can also call the hosted MCP tools at https://api.sapiom.ai/v1/mcp/pay. Both take the key in an x-api-key header.
> Keys that start with sk_test_ reach the sandbox, a separate environment with its own users and cards, at the same addresses. Use test card numbers only there.
> Never ask a user for a card number, expiry date or CVV in chat. Users enter card details only on Sapiom's hosted pages.
> Check the merchant before buying. Use purchase.type ucp_checkout only when the merchant check returns supported. Otherwise use browser_checkout.
> Follow the nextAction in each transaction result. Action links are secrets for the intended user only.
> Use one idempotency key per transaction. Resume an unanswered create with the same request and key. If a UCP update or cancellation is uncertain, stop and hand off to a person. If a browser cancellation is uncertain, read the transaction and resend the same cancellation, with the same key, only if it is not closed. Never start a new transaction to escape an uncertain outcome.
> For a ucp_checkout purchase, report an order as placed only when order.outcome is confirmed; if it is unknown, stop and hand off to a person. A browser_checkout purchase has no order confirmation (order is null): confirm the order on the merchant's page.

# Manage users

> Create a Sapiom user and user key for each of your users, handle users that already exist, store keys safely and remove users.

Each user who buys through your agent needs their own Sapiom user and user key. This page covers setting them up for real users from your backend. To try it once with a test user, see the [quickstart](https://docs.sapiom.ai/quickstart.md). In the API, a user is called a tenant.

**You need:** your [platform key](https://docs.sapiom.ai/users/platform-keys.md), kept in your backend. Never give it to your agent.

## When to create a user

Create a Sapiom user and key once per user, the first time they need one: when they sign up, or when they first ask your agent to buy something. Reuse both after that.

## Create the user

Use your own ID for the user as `externalId`. It links the Sapiom user to your user, so the same person never gets two Sapiom users.

```bash theme={null}
curl https://api.sapiom.ai/v1/tenants \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","externalId":"user_123"}'
```

Store the returned `id` with your user record. The next examples call it `BUYER_ID`.

### If the user already exists

`409 Conflict` means a user with that `externalId` already exists, for example after a retry. Look it up instead of creating another:

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants?filter%5BexternalId%5D=user_123" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY"
```

## Create and store the user key

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants/$BUYER_ID/api-keys" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"user_123"}'
```

The response includes `plainKey`, shown only once. Store it encrypted with your user record and reuse it for every session with that user. Your backend passes it to your agent and browser worker for that session. See [Connect your agent](https://docs.sapiom.ai/users/connect-agent.md).

## Remove a user

To remove a user, for example when a user closes their account, call `DELETE /v1/tenants/{BUYER_ID}` with your platform key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.