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

# Get a platform key to manage users

> Create a Sapiom platform key in the dashboard and give each user their own isolated Sapiom user and user key.

A platform key lets your backend create a Sapiom user and user key for each of your users. Only a platform key can manage users. Keep it out of your agent, which acts for one user at a time with that user's key.

## Why use a platform key

Your agent shops for many users, and each user's cards and transactions must stay theirs. Sapiom enforces that with two kinds of key:

| | Platform key | User key |
| - | - | - |
| Held by | Your backend only | Your backend, passed to the agent for one user's session |
| Created | In the dashboard | By your backend with `POST /v1/tenants/{tenantId}/api-keys` |
| Can | Create, list and delete users, and create user keys | Save cards and run transactions |
| Reaches | Every user in your organization | One user's cards and transactions |

A user key can't create users or keys, read or change [spending limits](https://docs.sapiom.ai/controls/spending-limits.md), or reach another user's data. You get isolation between your users without building it yourself:

* **One user per session.** An agent working for one user can't read or charge another user's card, even if a prompt or a bug tells it to.
* **Limits the agent can't raise.** The agent can't raise a spending limit to get past a denial.

## Create a platform key

**You need:** the owner or admin role in your Sapiom organization. Members don't see **Create platform key**.

1. Sign in and open [API keys](https://app.sapiom.ai/dashboard/api-keys) in the sidebar. To create a sandbox key, turn on **Sandbox** in the sidebar first.
2. Click **Create platform key**.
3. Enter a **Name**, such as `Production`, and an optional **Description**. Click **Create**.
4. Click **Reveal key**, copy it, and store it in your backend's secret manager as `SAPIOM_PLATFORM_KEY`. Then click **Done**.

The key is shown only once. If you lose it, create a new one.

![API keys dashboard with API keys selected in the sidebar and the Create platform key button outlined in red](https://mintcdn.com/sapiom-1f975ca2/gt9p8qSL_kjaQDIu/images/platform-key-create.png?fit=max\&auto=format\&n=gt9p8qSL_kjaQDIu\&q=85\&s=884a1dc826c19824d3ff14198c5a5b93)

Create a platform key on the API keys page

A platform key has three permissions: `org.tenants.read`, `org.tenants.write` and `org.transactions.write`. See [Permissions](https://docs.sapiom.ai/api-reference/overview.md#permissions).

> [!NOTE]
>
> You can set up users and cards right away. Before their cards can pay
> merchants in production, [request access](https://docs.sapiom.ai/request-access.md) so Sapiom can
> enable your account. To build and test first, use the [sandbox](https://docs.sapiom.ai/sandbox.md).

## Check the key

List your users:

```bash theme={null}
curl https://api.sapiom.ai/v1/tenants \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY"
```

A `200` response confirms the key can manage users. Next, [create a Sapiom user for each of your users](https://docs.sapiom.ai/users/create-users.md).

## Replace or revoke a key

To replace a platform key, create a new one, switch your backend to it, and check that it works. Then click **Revoke** on the old key in [API keys](https://app.sapiom.ai/dashboard/api-keys). Creating a key doesn't revoke the old one, and requests made with a revoked key are refused.

## Errors

| Response | Cause |
| - | - |
| `403` `Missing required permissions: org.tenants.write` | The key came from **Create key**, not **Create platform key**. |
| `403` `Tenant management is restricted to the organization's internal tenant. External tenant API keys cannot manage tenants.` | You sent a user key. Use your platform key. |


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