Authentication
Machines authenticate with an API key. There are no cookies and no sessions.
Creating a key
Section titled “Creating a key”Keys are created by anyone who may manage users: the Administrator and, for support cases, the Operator role. Open Settings, Integrations and create an API key. You choose a name (up to 32 characters) and a lifetime of 90, 180 or 365 days. The plain text key is shown exactly once. Store it like a password. A key can be revoked at any time. Creating and revoking keys is recorded in the audit log.
The key belongs to the person who creates it. If that person’s account is deactivated or anonymized, the key stops working (401).
Using a key
Section titled “Using a key”Send it in the x-api-key header with every call:
GET /api/invoices HTTP/1.1Host: <your-instance>x-api-key: <your-key>What a key may do
Section titled “What a key may do”A key can do at most these things, whoever owns it:
| Right | Meaning |
|---|---|
invoices.upload |
deliver invoices |
invoices.read |
read invoices, their export state and events |
invoices.decide_external |
report an approval made outside fineelik |
agreements.integration_write |
hand over contracts from ELO and their documents |
agreements.integration_read |
read the state of contracts from ELO |
It can also never do more than its owner may. Reporting an approval needs the right invoices.decide_external on the owner, which at present only the Administrator role has. The same goes for the two contract rights (module Contracts), see Contracts from ELO.
Route lock
Section titled “Route lock”A key only reaches routes whose rights are all in the list above. Every other route answers 403, even if the owner is an administrator. This includes everything meant for signed-in people, for example personal data requests, absence entries or the approval inbox with expenses and travel.
Reachable with an API key today:
- delivering invoices (upload, ELO handover)
- invoice list, detail, document, history and approval proof
- events and export state
- lookup by document GUID
- reporting an approval made outside fineelik
- handing over contracts from ELO and reading their state
A few read-only routes of the web application (counters, evaluations) are reachable with a key as well. They are not part of this documented interface and may change with the application.
Webhooks cannot be seen or created with an API key. They are managed by a signed-in person, see Webhooks.
Binding to a company
Section titled “Binding to a company”In fineelik a company (Buchungskreis) is one legal entity with its own accounts, vendors and rules.
When you create a key you can bind it to one company. Then:
- everything the key delivers lands in that company (one ELO component per client, one key each),
- reading is just as strict: every reachable route only sees invoices of that company, and only as long as the key’s owner can see it (checked on every request).
Without a binding the key uses the default company of the instance. A key without a valid company reads nothing and gets 403 (api_key.no_company) when delivering.
Invoice ids and statuses from another company never appear in any answer. Asking for them gives 404.