Credentials
The API's two credentials, which headers each call carries, and which one can live in the browser.
The API has two distinct credentials, and they are not interchangeable. Which one you use depends on where your code runs and what data it needs to see.
Commerce API key
This is the classic integration: your backend operates across every member of the
commerce. The API key goes in the Authorization header:
Authorization: Bearer {api-key}This credential works with Consumptions, Benefits and Clients. No other header is needed: the key already identifies the commerce.
It is a secret
The API key grants access to the data of all your members. Never put it in the frontend, in a mobile app, or in a repository. If it leaked, write to us at hola@loybox.com.ar so we can rotate it.
End-user token
Meant for wiring Loybox straight into your frontend and using it as a loyalty engine: the user signs in with a code emailed to them and from there looks up their points, buys benefits and sees their history.
Two headers travel:
Authorization: Bearer {user-access-token}
X-Commerce-Id: {your-commerce-id}This credential works with Authentication, My account and Public. This token can live in the browser: it only sees that user's data in your commerce.
The X-Commerce-Id header
X-Commerce-IdintegerheaderrequiredId of the commerce integrating the API. Every response is scoped to this commerce.
It is required on every Authentication, My account and Public endpoint, even the ones that carry no token. It is the header that scopes the response to your program: the same user can be in several Loybox programs, and with this header they only see yours.
It is not a secret: it goes in the frontend without a problem. What it does is scope, not authorize.
The sign-in flow
Request the code
POST /v1/auth/otp/request with the
user's email. They receive a 6-digit code.
Verify it
POST /v1/auth/otp/verify with
the email and the code. It returns an access token (access) and a refresh token
(refresh). If the email had no Loybox account, one is created, and either way
the user ends up subscribed to your commerce's program.
Use the session
From there on, calls to My account go with
Authorization: Bearer {access}.
Renew it
When the access expires,
POST /v1/auth/refresh returns a
new one from the refresh, without asking the user for another code.
The code expires in 10 minutes and allows 5 attempts. Requesting a new code invalidates the previous one.
Summary
| Commerce API key | End-user token | |
|---|---|---|
| Header | Authorization: Bearer {api-key} | Authorization: Bearer {access} + X-Commerce-Id |
| Where it lives | On your server only | Can live in the browser |
| What it sees | Every member of the commerce | Only that user, only in your commerce |
| Expires | No | Yes, renewed with the refresh |
| Sections | Consumptions, Benefits, Clients | Authentication, My account, Public |