Developers
Authentication
Every API request carries an organisation API key as a bearer token. Keys are created by the organisation’s owners and admins, and each one is tied to the person who created it.
Sending your key
Put the key in the Authorization header of every request:
Authorization: Bearer km_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA key is km_live_ or km_test_ followed by 40 URL-safe characters. Treat it like a password: keep it on your server, never in browser code or a mobile app, and never in source control.
Creating a key
- An owner or admin of the organisation opens Settings → Integrations in Kumry.
- They name the key, choose its access (read, or read and write), and optionally an expiry of 1 to 730 days.
- Kumry asks them to confirm with multi-factor authentication.
- The full key is shown once. Copy it into your secret store straight away; Kumry keeps only a SHA-256 hash and the first 16 characters, so it can be recognised in the list but not recovered.
An organisation can hold up to 25 live keys at a time.
Access levels
A key's access maps onto Kumry's own roles, so the same permission checks apply as for a person.
| Scopes | Acts as | Can |
|---|---|---|
| read | Viewer | Read the organisation’s data that a viewer can see. |
| read + write | Editor | Read, and create or update records as an editor can. |
A key can never act as an owner or admin.
What a key cannot do
A key carries no signed-in session. Anything Kumry asks a person to confirm with multi-factor authentication is refused to a key. Keys are also kept away from sign-in, billing, membership and administration. Requests to these paths answer 403 with the code API_KEY_PATH_FORBIDDEN:
/auth/billing/admin/internal/practice/tenants/api-keys/tenants/webhooks/tenants/invite/tenants/members/tenants/current/tenants/onboarding/tenants/entity-groups/tenants/data-settings/settings/team/help
Rotation, expiry and revocation
- Rotate a key to get a new secret with the same name, access and expiry. The old key keeps working for 24 hours so you can roll the change out without an outage.
- Revoke a key and it stops working straight away.
- A key also stops working when it expires, when the person who created it is no longer an owner or admin of the organisation, or when the organisation is no longer active.
- Kumry records when each key was last used and how many requests it has made.
An invalid, expired or revoked key answers 401 with the code API_KEY_INVALID.
Audit
Requests made with a key are recorded against that key and the person who issued it, so the organisation's activity history can tell work done through an integration from work done in the app.
API access is available on request
Organisation owners and admins create API keys and webhooks under Settings → Integrations. If you are building an integration and want to talk it through first, get in touch.