> ## 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 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. Send each one only to the person `nextAction.actor` names.
> 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.

# Set up your platform

## Get your platform connected to Sapiom&#x20;

Get an API key and start making requests. From the [API keys](https://app.sapiom.ai/dashboard/api-keys) view, click "Create platform key."

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

API keys → Create platform key

A platform key is the highest permission API key. With the Sapiom platform key, you can create and remove users and make purchases for them.

```bash theme={null}
# Check the key: a 200 response means it can manage users.
curl https://api.sapiom.ai/v1/tenants \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY"
```

## Give a user a Sapiom ID

Each of your users will need a Sapiom user ID before they can make purchases through Sapiom. After creating the Sapiom user ID, generate and save their user API key. A User API Key is a regular Sapiom API key scoped to one user. Your agent will use this ID and key when making purchases on behalf of your user. Unlike your platform key, you may share this User API key with an agent so that it may take actions on behalf of the user.

```bash theme={null}
# "Tenant" is the API's word for a Sapiom user.
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:
export USER_ID="..."
```

`409` means it exists, so look it up by `externalId`.

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

Then create the user's key. Store the `plainKey` encrypted.

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

# "plainKey" is shown only once.
```

## Connect your agent as that user

One MCP connection per session with the user key, never  shared between users.

A user key connects to one user's cards and purchases.

```typescript connect-sapiom.ts theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

// One connection per session, with that user's key. Close it when the session ends.
export async function connectSapiom(userKey: string) {
  const transport = new StreamableHTTPClientTransport(new URL("https://api.sapiom.ai/v1/mcp/pay"), { requestInit: { headers: { "x-api-key": userKey } } });
  const client = new Client({ name: "your-agent", version: "1.0.0" }); await client.connect(transport); return client;
}
```

## Revoke and remove

Revoke a key in [API keys](https://app.sapiom.ai/dashboard/api-keys).&#x20;

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

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