Authentication
Every request carries an API key as a Bearer token:
Authorization: Bearer sk_test_your_key_hereThe x-api-key header is not accepted. Requests go to https://gp.useyona.com whichever key you use; the key decides whether you are on the sandbox or the live service.
Keys
- Keys are created in the Yona app under API keys, by a signed-in user. A key can never create, rotate or revoke keys: those operations answer
403withAUTH018. - The secret is shown once, at creation and at rotation. Store it then.
- A key starts with
sk_test_(sandbox) orsk_live_(live). The environment is fixed for the life of the key. - A key may carry an expiry. An organisation may hold up to 50 active keys.
What a key may do
Each key is granted a set of capabilities when it is created, either from a preset or as an explicit list. There are 42 capabilities.
| Preset | Capabilities | Covers |
|---|---|---|
read_only | 17 | Reading invoices, buyers, items, received invoices, billing, the organisation and webhook deliveries |
invoicing | 39 | Everything in read_only, plus creating, finalising, submitting, sending and downloading invoices, buyers, items, and verifying tax numbers |
full_integration | 42 | Everything, including cancelling invoices with a credit note |
read_only is the default. A request that needs a capability the key lacks is answered 403 with AUTH019.
What a key may never do
These operations are for signed-in users and are done in the Yona app. With a key they answer 403 with AUTH018:
- creating, rotating or revoking API keys;
- connecting to the tax authority, refreshing the connection, installing the crypto key, or disconnecting;
- creating, updating, deleting or rotating the secret of a webhook endpoint (a key can list and test them, and read deliveries);
- buying credits;
- changing invoice settings;
- members, invitations and roles.
The API reference says, next to every operation, whether a key may call it.
How a key is checked
The gateway exchanges the key for a short-lived token, valid for at most ten minutes, and caches the result. You never handle that token. Revoking a key takes effect on its next request.
Rotating a key issues a new secret and keeps the old one working for a grace period, one day by default and seven at most, so you can switch without a gap.
Live keys
Creating a sk_live_ key needs three things, each with its own refusal:
| Need | Refusal |
|---|---|
| The organisation has been approved for live access | 403 BIZ006 |
| Live mode is switched on for the organisation | 403 BIZ005 |
| The session creating the key has a second factor | 403 AUTH025 |
See Sandbox and live for the path to live access.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | AUTH004 | No usable token on the request |
| 401 | AUTH021 | The key is not valid |
| 401 | AUTH022 | The key has expired |
| 401 | AUTH041 | The key was revoked |
| 403 | AUTH018 | This operation is for signed-in users |
| 403 | AUTH019 | The key lacks a capability the operation needs |
Keep keys safe
- Keys are server-side only. Never ship one in a browser, a mobile app or a public repository.
- Read keys from the environment, not from source control.
- Give each integration its own key with the smallest preset that works, and name it after the system that holds it.
- Rotate on a schedule, and revoke at once if a key may have leaked.