API keys
Create a key, send it with every request, and what a 401 or 403 means.
Create a key
In the Yuze dashboard, go to Company, then API, and choose Create key.
- Name it after the tool it is for, for example Supy.
- Tick the access it needs. Give it only what that tool reads.
- Leave every branch ticked, or untick the branches it should not see.
- Set an expiry date if the key is only needed for a while.
| Access | What it reads |
|---|---|
company:read | Your company |
branches:read | Branches and payment methods |
transactions:read | Transactions and their line items |
payments:read | Payments, and the payment totals on transactions |
reports:read | Sales summary, product sales and payment types |
The key is shown once, when you create it. Copy it into a password manager or your tool's secret store straight away. Yuze cannot show it again. If you lose it, delete it and create a new one.
Only the account owner, or a user given the Company permission, can create or delete keys. A company can have up to 20.
Send a key
Send it in the Authorization header on every request.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://europe-west2-fyre-pos.cloudfunctions.net/publicApi/v1/me"GET /v1/me needs no access, so it is the quickest check that a key works. It returns the key's name, branches and access.
Keep the key out of source code and browser apps. Use one key per tool, so deleting one does not break the others. A deleted key stops working on the next request.
401 and 403
| Status | Code | What it means |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer header was sent |
| 401 | invalid_api_key | The key is wrong, deleted, or for the wrong environment |
| 401 | expired_api_key | The key's expiry date has passed |
| 401 | revoked_api_key | The key was revoked |
| 403 | insufficient_scope | The key does not have the access this endpoint needs. details.requiredScope names it |
| 403 | branch_forbidden | You asked for a branch the key cannot read |
A transaction or payment in a branch the key cannot read returns 404, as if it did not exist.