> ## 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 end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer'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 test environment with its own buyers and cards, at the same addresses. Use test card numbers only there.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers 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 buyer 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 buyers

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

A platform key lets your backend create a buyer and buyer key for each of your users. Only a platform key can manage buyers. Keep it out of your agent, which acts for one user at a time with that user's buyer 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 | Buyer 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 buyers, and create buyer keys | Save cards and run transactions |
| Reaches | Every buyer in your organization | One buyer's cards and transactions |

A buyer key can't create buyers or keys, read or change [spending limits](https://docs.sapiom.ai/controls/spending-limits.md), or reach another buyer'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 [Developers → API keys](https://app.sapiom.ai/dashboard/developers/api-keys).
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.

![The Developers page on the API keys tab, with the Create platform key and Create key buttons circled](https://mintcdn.com/sapiom-1f975ca2/q6wuBi6kpSnAblqN/images/platform-key-create.png?fit=max\&auto=format\&n=q6wuBi6kpSnAblqN\&q=85\&s=69b228ecb0bdabc9b1321eebae653bad)

Developers → API keys in the Sapiom dashboard

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 buyers 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 buyers:

```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 buyers. Next, [create a buyer for each user](https://docs.sapiom.ai/buyers/create-buyers.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 [Developers → API keys](https://app.sapiom.ai/dashboard/developers/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 buyer key. Use your platform key. |


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