API reference

API keys

REST endpoints to list, create, update, and revoke API keys for your organization. The raw secret is returned only once at creation.

API keys

The API keys management API is the programmatic counterpart of the Portal's Settings → API keys screen. It lets Owners and Admins of an organization mint, list, relabel, deactivate and revoke API keys without going through the UI — useful for provisioning integrations, rotating keys from a CI pipeline, or auditing the active key set from a back-office tool.

Every endpoint in this group lives under /api/v1/org/api-keys and is administrative, the same way the Webhooks management endpoints are.

Unlike most of the API reference, API-keys management routes are not API-key authenticated. They sit behind the Portal JWT middleware and additionally require the calling user to have the Owner or Admin role on the organization. There is no API-key scope that grants access to API-key administration — generate a Portal session token (POST /api/v1/auth/login) and use it as Authorization: Bearer <jwt>. See Authentication › JWT authentication.

The raw API key value is returned only once, in the key field of the POST /api/v1/org/api-keys response. It is hashed before being persisted and there is no endpoint that can return it again — store it in your secret manager before the response is discarded. If the key is lost, revoke it (DELETE) and create a new one.

The error envelope, rate limits and pagination conventions are documented once on API overview; only the per-endpoint error codes are listed in full on this page.

Scopes

POST /api/v1/org/api-keys requires at least one scope. The available scopes are:

Scope	Grants
`receipts`	Full receipt access (store, list, get).
`receipts:read`	Read-only receipt access.
`receipts:admin`	Receipt administration (storno, history exports).
`reports`	Report generation and read access (X / Z / JE / MF).
`devices`	Full device access (read + write + claim/release).
`devices:read`	Read-only device access (list, status, alerts, info).
`devices:write`	Device write operations (register, update, delete, claim, configuration commands).
`commands`	Submit, list, get and cancel fiscal commands (Commands).
`all`	Equivalent to every other scope. Use sparingly — prefer the most specific scope set.

The full scope catalogue, including which routes accept which scopes, is on Authentication › Scopes.

GET /api/v1/org/api-keys

Lists all API keys for the organization, newest-first. The hashed key is never returned; only the prefix (first 12 characters of the original key plus …) is exposed so you can identify which key is which.

Auth: Portal JWT.

Response (`200 OK`)

[
  {
    "id": "apikey_abc123",
    "prefix": "ebon_live_a…",
    "label": "Accounting integration",
    "scopes": ["receipts", "reports"],
    "active": true,
    "createdAt": "2026-03-01T12:00:00.000Z",
    "lastUsed": "2026-04-09T08:09:55.000Z"
  }
]

lastUsed is null for keys that have never been used to authenticate a request.

Example

curl https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>"

Error codes

UNAUTHORIZED (401) — missing or invalid JWT.

The full HTTP catalogue is on API overview › HTTP error code catalogue.

POST /api/v1/org/api-keys

Generates a new API key with the specified label and scopes. The raw secret is returned once in the key field of the response — store it immediately.

Auth: Portal JWT, role Owner or Admin.
Tier check: the request goes through the enforceApiKeyCreation middleware. The Free plan does not allow API key creation; the request is rejected with 403 TIER_LIMIT_EXCEEDED.

Request body

Field	Type	Required	Notes
`label`	string	yes	Human-readable label, 1–100 chars.
`scopes`	string	yes	At least one entry from the `ApiKeyScope` enum (see Scopes above).

Response (`201 Created`)

{
  "id": "apikey_abc123",
  "key": "ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "prefix": "ebon_live_a…",
  "label": "Accounting integration",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-04-09T08:10:00.000Z"
}

Example

curl -X POST https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Accounting integration",
    "scopes": ["receipts", "reports"]
  }'

Error codes

VALIDATION_ERROR (400) — body failed Zod validation (empty label, label > 100 chars, empty scopes array, unknown scope value).
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller does not have Owner or Admin role.
TIER_LIMIT_EXCEEDED (403) — API keys are not available on the Free plan; upgrade to Pro to create API keys.

PATCH /api/v1/org/api-keys/{keyId}

Updates the label and/or active state of an API key. At least one field must be provided. Scopes are immutable — to change the scope set, revoke the key and create a new one.

Auth: Portal JWT, role Owner or Admin.

Path parameters

Parameter	Type	Notes
`keyId`	string	API key document ID.

Request body

Field	Type	Notes
`label`	string	1–100 chars.
`active`	boolean	Toggle the key on/off. An inactive key is rejected at the auth layer.

Response (`200 OK`)

{
  "id": "apikey_abc123",
  "prefix": "ebon_live_a…",
  "label": "Accounting integration (renamed)",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-03-01T12:00:00.000Z",
  "lastUsed": "2026-04-09T08:09:55.000Z"
}

Example

curl -X PATCH https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Error codes

VALIDATION_ERROR (400) — body failed Zod validation, or empty body (no fields to update).
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller does not have Owner or Admin role.
NOT_FOUND (404) — no API key with that ID in your organization.

DELETE /api/v1/org/api-keys/{keyId}

Permanently revokes an API key. The key is removed from Firestore — there is no soft-delete. Any in-flight requests authenticated with the key continue to complete; subsequent requests are rejected with 401 UNAUTHORIZED. Returns 204 No Content on success.

Auth: Portal JWT, role Owner or Admin.

Path parameters

Parameter	Type	Notes
`keyId`	string	API key document ID.

Example

curl -X DELETE https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>"

Error codes

UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller does not have Owner or Admin role.
NOT_FOUND (404) — no API key with that ID in your organization.