Authentication
Send your key in an api-key header on every request:
api-key: bik_your_key_hereThat is the whole scheme. There is no OAuth flow, no token exchange, and no refresh: the key is the credential until the merchant revokes it.
Where keys come from
The merchant issues them, from their Bione company admin. You cannot create one yourself, and neither can Bione support — a key belongs to the merchant whose data it opens.
When they issue one, they choose:
- which scopes it carries — see the table below;
- whether it expires — an expiry is optional and can be set at issue time.
The plaintext is shown once, at the moment of issue. Bione stores only an argon2 hash of it, so a key that is lost is not recoverable and has to be reissued. Ask the merchant to send it to you over something better than email.
Rotating a key
There is no in-place rotation. To roll a key: the merchant issues a second one, you switch to it, then they revoke the first. Both work at the same time in between, so there is no window where your integration is down.
Revocation takes effect on the next request.
What a key can reach
A key opens exactly one merchant's data. There is no parameter, header or path that widens it — asking for another merchant's order by id answers 404, the same as an id that does not exist.
One scope reads narrower here than its name suggests. cashback:read is the same permission a merchant grants their own staff, where it also opens the cashback reports and the full transaction history — but this API publishes only the customer's current balance, on the customer routes. There is no ledger and no summary endpoint to reach.
Scopes
Your key carries some subset of the scopes below. The merchant chooses them when they issue the key and can change them at any time. A call needing a scope your key does not hold is refused with 403, and the refusal does not say which scope was missing.
| Scope | What it allows |
|---|---|
orders:read | View orders, their items, portions and refund history |
orders:write | Create orders, advance their status, mark paid, reassign portions |
products:read | View the catalogue and product tax information |
products:write | Create, update and delete products |
customers:read | View customers and their standing |
customers:write | Create and update customers |
cashback:read | View cashback wallets, summaries and ledgers |
Scopes grant exactly themselves. There is no hierarchy: products:write does not imply products:read, and there is no administrative scope that implies everything. If you need both, ask for both.
Some things are deliberately not grantable to a key at all — cancelling orders, issuing refunds, adjusting cashback, managing employees or issuing further keys. Those are a person's decisions inside the merchant's own admin, and no integration can be given them.
Keeping a key safe
- Treat it like a password: it is a bearer credential, and anyone holding it is you.
- Keep it server-side. A key in a mobile app or a browser bundle is a key you have published.
- Store it in your secret manager, not in your repository.
- If you think it leaked, ask the merchant to revoke it. That is instant and costs them nothing but issuing a replacement.
Rate limits
The budget is per merchant, not per IP address. Running your integration across several servers does not multiply it, and sharing an office network with another integrator does not divide it.
Going over answers 429. Back off and retry.