Skip to main content
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: A buyer key can’t create buyers or keys, read or change spending limits, 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.
  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

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.
You can set up buyers and cards right away. Before their cards can pay merchants in production, request access so Sapiom can enable your account. To build and test first, use the sandbox.

​
Check the key

List your buyers:
A 200 response confirms the key can manage buyers. Next, create a buyer for each user.

​
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. Creating a key doesn’t revoke the old one, and requests made with a revoked key are refused.

​
Errors