API keys

An API key is the credential a POS partner, accounting integration or any other external system uses to authenticate against the e-bon API. It is machine-to-machine: the key is sent in the Authorization header of every request and identifies the organization the call is being made on behalf of, not a human user. API keys are completely separate from the email-and-password login that humans use to access the Portal.

Find your API keys

Open the Portal sidebar and pick API Keys. The page lives at /portal/api-keys and lists every key currently issued for your organization, together with its label, prefix, scopes, last-used timestamp and active/inactive state.

Generate a key

Scopes

Scopes are the permissions attached to an API key. A request authenticated with a given key can only reach endpoints covered by that key’s scopes; anything else returns a 403 Forbidden. e-bon ships nine scopes:

• all — Full access. Every endpoint, every resource. Use this only for trusted internal integrations where narrowing scopes does not buy you anything; prefer the specific scopes below for partner integrations.
• receipts — Receipts (read + write). Issue receipts and read back the receipt history.
• receipts:read — Receipts (read-only). Read the receipt history without being able to issue or modify anything. Ideal for accounting exports and reporting dashboards.
• receipts:admin — Receipts (admin operations). Storno reversals and archival operations on existing receipts. Grant this only to the integration that handles refund flows.
• reports — Reports. Read X, Z, MF (Memorie Fiscală) and JE (Jurnal Electronic) reports across the organization’s devices.
• devices — Devices (read + write). Full device management: register new AMEFs, rename or delete existing ones, and read device state.
• devices:read — Devices (read-only). Read-only access to the device fleet — model, status, location, last-seen timestamp.
• devices:write — Devices (write). Register, rename and delete devices without granting read access to receipts or reports.
• commands — Commands. Queue print/operations commands (for example trigger an X or Z report) against the organization’s devices.

Manage existing keys

Each key in the list has two actions next to it: a pencil edit button and a red delete button.

• Edit opens a modal where you can change the label and toggle the Active switch. Deactivating a key (toggle off, save) keeps the key in the list but causes every request using it to fail with 401. Re-enable it the same way. This is the right tool for temporarily suspending an integration without throwing the secret away.
• The Last used timestamp on each row shows how long ago the key was last accepted by the API. A key that hasn’t been used in months is a good candidate for cleanup.
• The Active / Inactive badge reflects the same state as the toggle in the edit modal.

Rotate or revoke a key

There is no rotate-secret operation for API keys — the secret is only ever shown in the reveal modal at creation time, and the API keeps only its hash. To rotate, create a new key, switch your integration to the new key, and then delete the old one.

To revoke a key, click the red trash button on the row and confirm in the Delete API Key modal.

Webhook secrets are different. Webhooks have their own rotate-secret flow on the Settings → Webhooks page; that is unrelated to API keys. See Webhooks below.

Use the key in a request

Send the key in the standard Authorization: Bearer … header on every request. The exact value to send is whatever was displayed in the reveal modal — copy it verbatim, including the ebon_live_… prefix.

curl https://api.e-bon.ro/api/v1/devices \
  -H "Authorization: Bearer ebon_live_<orgId>_xxxxxxxxxxxxxxxx"

The same header works for any e-bon API endpoint covered by your key’s scopes:

GET /api/v1/devices HTTP/1.1
Host: api.e-bon.ro
Authorization: Bearer ebon_live_<orgId>_xxxxxxxxxxxxxxxx
Accept: application/json

A failed authentication returns 401 Unauthorized (key missing, deleted or deactivated). A request that authenticates but is outside the key’s scopes returns 403 Forbidden.

For an end-to-end walkthrough of issuing your first receipt against the API with one of these keys, see the Integration walkthrough.

Webhooks (related)

API keys are how an external system pulls data from e-bon. Webhooks are the other half of the integration story — how e-bon pushes events out to your URL when something happens (a receipt is issued, a Z report closes, a device goes offline). Configure them on the Settings → Webhooks page at /portal/settings/webhooks.

You will typically use both: an API key so your system can read and act on data, and a webhook subscription so e-bon can notify your system the moment a relevant event occurs — no polling required. The full webhook event reference and signature-verification details ship as part of the API reference.

Next steps

• Devices — see what the devices and devices:read scopes give you access to.
• Receipts — the data behind the receipts* scopes.
• Reports — what reports reads and what commands can trigger.