Skip to main content

Authentication

In-store requests are made server to server and authenticated with an API key. The key identifies your business, so every request acts on your own data and nothing else.

Your API key​

An API key looks like this:

bndl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

You create keys in the Boundless dashboard. The full value is shown once, at creation — store it in your server's secret manager. If a key is lost or exposed, revoke it and create a new one. When you rotate a key, the replacement is issued while the old value keeps working for a grace period, so you can roll credentials across a till fleet without downtime.

Keep keys server-side

An API key can take payments in your name. Never ship it in till firmware, a mobile app binary, or anything a customer or store staff member could extract. If your architecture puts software directly on the terminal, that software calls your server, and your server calls Boundless.

Issue one key per environment, and rotate on a schedule and on any staff change with access to it.

Sending the key​

Send the key in the X-API-Key header:

curl https://api-live.kcpboundless.com/api/in-store/payments \
  -H "X-API-Key: bndl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If your HTTP client is easier to use with a bearer token, an Authorization header carrying the same key is also accepted:

curl https://api-live.kcpboundless.com/api/in-store/payments \
  -H "Authorization: Bearer bndl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Use one or the other. A request with no valid key is rejected with 401 Unauthorized.

The bearer form is prefix-gated

The Authorization header is recognised only when the token begins with the bndl_live_ prefix. Anything else on that header is ignored, and the request is rejected as unauthenticated. If a bearer request unexpectedly returns 401, check the prefix before anything else — or simply use X-API-Key, which has no such condition.

What a key can and cannot do​

A key is scoped to your business. It can take in-store payments, follow and reverse them, and manage your own stores and terminals. It cannot reach another business's data — a request that names a store or payment you do not own is rejected as not found.

Settlement and post-sale financial operations — refunds among them — are performed by signed-in dashboard users, not by a key.

Rate limits​

Requests are rate limited per key. Within normal point-of-sale volumes you will not encounter the limit; if a burst exceeds it, requests return 429 Too Many Requests with a Retry-After header — back off for the indicated delay, then retry. If you need a higher limit for a key, ask Boundless.