- Overview
- Authentication
- Errors and limits
- Code examples
- Moving from Classic
- KPIs
- KPI Categories
- KPI Categories / KPIs
- Breakdown Items
- KPI Entries
- KPI Frequencies
- KPI Icons
- KPI Units
- Reports
- Users
SimpleKPI AI › API reference
Authentication
Every request to the SimpleKPI AI API carries an API key as a bearer token. There is no other way in — no basic authentication, no key in the query string, no session cookie.
Authorization: Bearer skpi_your_api_key
The key alone identifies your account, so there is no separate account id, subdomain or username to send.
Creating a key
- Go to Settings → API Access and choose Create API Key.
- Name it after the thing that will use it, for example Nightly warehouse sync. The name is what you will look at when deciding whether a key is still needed.
- Optionally set an Expiry Date. Leave it blank for a key that does not expire.
- Grant each resource None, Read or Write. At least one permission is required.
- Choose Create API Key.
The key is shown once. Copy it straight into a password manager or your deployment secrets — it cannot be retrieved afterwards, and a lost key has to be replaced rather than recovered.
Keys begin with skpi_. That prefix exists so secret scanners can recognise one that has been committed by mistake.
Permissions
A key carries a set of scopes. Each endpoint requires one, and every endpoint page on this site names the scope it needs. The left column is what the key carries; the right is what the API Access screen calls it.
| Scope | Shown as | Covers |
|---|---|---|
kpis:read | KPIs (Read) | KPIs, categories, units, frequencies and icons. |
kpis:write | KPIs (Write) | Creating and changing KPIs, categories and units. |
entries:read | Entries (Read) | Reading KPI entries and running reports. |
entries:write | Entries (Write) | Adding, changing and deleting KPI entries. |
breakdownitems:read | Breakdown Items (Read) | Reading the items a KPI can be broken down by. |
breakdownitems:write | Breakdown Items (Write) | Creating, changing and deleting breakdown items. |
users:read | Users (Read) | Reading the people on the account. |
Write does not imply read. A key that only has entries:write can push entries but cannot list them back.
Note that the KPI lookups — units, frequencies and icons — sit under the KPIs scope rather than having their own, and reports sit underentries:read because a report is a view over entries.Breakdown items do have their own pair, so a key that can write KPIs cannot change how they are broken down unless you grant that too.
There is no users:write. The API only reads people;Users is read-only and everything else about an account's people is done in the app.
When a request is rejected
| Code | What it means |
|---|---|
401 | The key was missing, malformed, unknown, expired or revoked. Also returned when the Authorization header is sent more than once, or when the token contains whitespace. |
403 | The key is valid but does not carry the scope this endpoint needs. Check the scope named on the endpoint's section, then edit the key in Settings → API Access. |
The scheme word is not case sensitive, so bearer works as well asBearer. Everything else about the header is strict.
Managing keys
The keys table shows each key's name, when it was created and when it was last used. Last-used is the useful column: a key nothing has touched in months is usually one you can delete.
Deleting a key revokes it immediately. Anything still using it starts getting401 on its next request, so replace the key in your integration first, then delete the old one.
Give each integration its own key, scoped to only what it touches. If one leaks you can delete that key alone, without taking down everything else that talks to your account.
Related
- Using the SimpleKPI API — the same steps with screenshots of the app.
- Errors and limits