Connect your own software with API keys

The public API lets your own software, or your developer's, read and write your Kluvan records: products, customers, stock, reports, Books documents, HR people, CRM, subscriptions and the apps you have. You control each key: what it may do, for how long and for which branch.

Before you start

• Only the owner can make and revoke keys.
• A key never opens an app your organisation does not have, and every rule of your plan, your apps and your branches still applies.

Steps

1. Open Settings → Developer access.
2. Under New key, type a Name you will recognise, for example "Warehouse scanner".
3. Set Valid for days (1–365). The default is 90.
4. Under Branch, keep All branches or pick one branch.
5. Under Can see, tick each scope the key needs. Each says Read or Write, for example Products · Read.
6. Tick the sentence that you authorise the selected access.
7. Press Make the key.
8. Copy the key now. It is shown only this once.
9. Give the key to your software. It sends it in the Authorization: Bearer header.

Calling the API

• The address is https://api.kluvan.com/v1/public-api. The Developer guide (/developers) shows examples and every operation with the scope it needs. OpenAPI 3.1 downloads the full contract, with request fields.
• Every write needs an Idempotency-Key: a new UUID per change. If the answer is lost, send the same request with the same key again, for up to 7 days; it is not applied twice. The same key with a changed request is refused.
• A change to an existing record also sends the record's current version (v), so an older copy never overwrites a newer one.
• Amounts are in the currency's smallest unit (150.00 is 15000).
• Lists of app records return up to 50 records and a next value; pass it as after to get the next page.
• Up to 120 requests a minute per key. Past that, the answer is 429 with Retry-After. Every error carries a code (see the error guide).

Good to know

• Write scopes change real records and can run an app's actions, with their stock and accounting effects. Give a key only the scopes it needs.
• Branch keys read branch records only. Catalogue, customer, CRM, HR and subscription operations need a key for all branches.
• Kluvan keeps only a fingerprint (hash) of each key. Lost a key? Revoke it and make a new one.
• Revoke stops a key at once. A key also stops on its last day. You can hold up to 20 keys.
• API activity lists each call: time, operation, key and status. Request bodies and keys are never recorded.
• The API does not offer billing, sign-in, payment collection or webhooks: there are no outgoing notifications, so your software reads the lists it needs.
• A signed-in browser session cannot call this API, and keys for assistant apps are separate: see connect an assistant app.