Manage buyers

Each user who buys through your agent needs their own Sapiom buyer and buyer key. This page covers setting them up for real users from your backend. To try it once with a test user, see the quickstart. In the API, a buyer is called a tenant. You need: your platform key, kept in your backend. Never give it to your agent.

When to create a buyer

Create a buyer 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 buyer

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

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 buyer already exists

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

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

Create and store the buyer key

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.

Remove a buyer

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

Get started

Buyers

Cards

Transactions

Governance

Security

Early access

When to create a buyer

Create the buyer

If the buyer already exists

Create and store the buyer key

Remove a buyer

​When to create a buyer

​Create the buyer

​If the buyer already exists

​Create and store the buyer key

​Remove a buyer

When to create a buyer

Create the buyer

If the buyer already exists

Create and store the buyer key

Remove a buyer