Authenticate API requests

Every request to the e-bon API must carry one of two credentials: an API key (for server-to-server integrations and POS partners) or a Portal access token (for users signed in to the e-bon Portal or the on-device app). This page shows you how to obtain each one, how to send it, and what to do when authentication fails.

Choose your authentication method

The two credentials are not interchangeable. API keys are bound to an organization and have scopes. Portal tokens are bound to a user inside an organization and have a role.

Authenticate with an API key

API keys are the recommended way to call the e-bon API from any server, POS terminal or back-office system. A key looks like this:

ebon_live_{orgId}_{32-hex}

The full key is shown to you only once, in the modal where you create it. Store it in a secure secrets store immediately — e-bon never displays the full secret again. The Portal will only show you the prefix (everything before the random tail) so you can identify the key later.

Send your first authenticated request

POST /api/v1/receipts HTTP/1.1
Host: api.e-bon.ro
Content-Type: application/json
x-api-key: ebon_live_abc123def456_0123456789abcdef0123456789abcdef

{ "deviceId": "dev_…", "items": [ … ] }

Authorization: Bearer ebon_live_abc123def456_0123456789abcdef0123456789abcdef

Revoke or rotate a key

API keys never expire on their own. To stop a key from working, open the Portal, find the key by its prefix and click Revoke. The next request that uses it returns 401 UNAUTHORIZED — API key is inactive. immediately.

There is no in-place rotation. To rotate a key, create a new one, update your secrets store, then revoke the old one once your deployment has rolled out.

Sign in to the Portal

Portal users sign in with email and password and receive a pair of tokens:

• An access token valid for 15 minutes, sent on every API call as Authorization: Bearer <token>.
• A refresh token valid for 7 days, used only to mint a new access token.

Complete the sign-in flow

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "you@example.com", "password": "…" }

GET /api/v1/devices
Authorization: Bearer <accessToken>

POST /api/v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }

POST /api/v1/auth/logout
Authorization: Bearer <accessToken>
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }

For full request and response shapes, see the Auth API reference.

Manage API key scopes

Every API key carries one or more scopes. Each request requires a specific scope; if the key is missing it, the API returns 403 FORBIDDEN — Insufficient scopes.

Manage user roles

Portal users have one of three roles, set when they are added to the organization:

Roles are evaluated on every Portal API call. If a user tries an action their role does not permit, the API returns 403 FORBIDDEN — Insufficient role.

Understand plan limits

Some actions are gated by your subscription plan:

When you hit a plan limit, the API returns 403 TIER_LIMIT_EXCEEDED with a message telling you which limit you hit and how to lift it (typically: upgrade your plan).

Handle rate limits

The API enforces three rate-limit buckets. All three return the same response on exhaustion:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests, please try again later.",
  "status": 429
}

Every 429 response includes a Retry-After header in seconds — wait at least that long before retrying.

Handle authentication errors

Every authentication and authorization failure returns a structured JSON envelope with a stable code field. Match on code (not on the human-readable message) when building error handling.

Where to go next

• Auth API reference — full request and response shapes for /auth/{register,login,refresh,logout,forgot-password}.
• API keys API reference — REST reference for managing keys programmatically.
• Portal: API keys — UI flow for creating, scoping and revoking keys.
• Portal: Sign up — bootstrap flow for the first Owner and the organization.
• Integration walkthrough — end-to-end sandbox loop that exercises authentication, receipts and webhooks together.