Authentication and scopes

The key

An API key is a string of the form hela_live_<40 characters> or hela_test_<40 characters>. It goes in the Authorization header:

Authorization: Bearer hela_live_3f9c…

Hela stores only the SHA-256 digest of the key. It is shown once, at creation; if lost, revoke it and create another. The key list shows only the prefix (hela_live_3f9c) to tell them apart.

Live and test

	hela_live_	hela_test_
Reads	real data	real data
Writes	yes	refused — 403 with code forbidden
Limit	600 req/min	60 req/min
Webhooks	receives events	receives events

A test key is the right key for development: you see your real sales, you can break nothing. Switch to live when your program writes.

Scopes

A key carries scopes, which are the product's permissions. The full list comes back from GET /companies/{id}/api-keys in scopes; the essentials:

Module	Scopes
Dashboard	dashboard:view
Sales	sales:view, sales:create, sales:update, sales:cancel, sales:refund
Purchases	purchases:view, purchases:create, purchases:update
Stock and catalogue	inventory:view, inventory:update, items:create, items:update
Partners	partners:view, partners:create, partners:update
Treasury	wallets:view, transactions:create, transfers:create
Reports	reports:view, exports:create
Events and webhooks	events:read, webhooks:manage
Integrations	integrations:manage

Three scopes exist only for keys: events:read (read the event journal), webhooks:manage (create and manage webhooks — what Zapier and n8n do), exports:create (start an export).

A few permissions can never be given to a key, because they touch the account's people or money: settings:members, settings:roles, developers:manage, billing:*. An attempt returns 400 scope-not-allowed:<scope>.

What a key sees

A key acts on behalf of the company, not of a person. In document history the author reads "API key ". Events it causes carry actor.kind = "api_key".

A key has no location restriction: it sees the whole company. If you need a per-shop view, filter (?businessUnitId=).

Revoking

DELETE /companies/{id}/api-keys/{keyId} or the button on the Developers page. Immediate; the next request gets 401. Webhooks created with that key stay: they are the company's objects, not the key's.

Good practice

• One key per use. "Zapier" and "Website" apart: revoking one does not break the other.
• Never a key in a browser or a distributed mobile app. The server calling Hela must be yours.
• Rotate keys that may have leaked: create the new one, switch, revoke the old one. No downtime.