API keys and scopes
A key is like a password for a program: who owns it, what it may do and what happens if it leaks.
A program cannot sign in with a password like a person — it has no hands for a keyboard and no phone for a second factor. So it gets a key: a long string that belongs to the company and carries exactly defined rights.
Scopes
A scope is the only thing a key is allowed to do. read is always included with any other scope, so a key with rides can also read the company profile, but cannot book a ride.
| Scope | Group | What it allows |
|---|---|---|
read | read | Company profile, whoami, service catalogue; included with every other scope |
rides | read | Ride list and detail, history and status timeline |
book | write | Create and cancel rides; changes company data |
vehicles | read | Vehicle list with plate, class and activity |
drivers | read | Driver list with code, name and status |
pricing | read | Price estimate via POST /v1/quote |
stats | read | Daily ride and revenue statistics |
webhooks | ops | Webhook health: endpoints, deliveries and the last attempt |
When a key lacks a scope the response is 403 with errors.forbidden — not 401. The difference matters: 401 means the key was not recognised, 403 that it was recognised but is not allowed.
Issuing a key
Issues a new key for the company in the session. Owner only (OWNER). The response contains the full secret — the only time it is visible.
| Field | Type | Required | Description |
|---|---|---|---|
name | string (2–80) | ✓ | A name that identifies the key (e.g. “Hotel bookings”) |
scopes | string[] | — | At most 8 values from the scope table |
expiresAt | ISO 8601 | — | The moment validity ends; empty means it never expires |
allowedIps | string[] | — | Up to 20 exact addresses or CIDR ranges (IPv4/IPv6) |
{
"id": "6a1f0c62-3a5e-4a5e-9d1e-0f1c2b3d4e5f",
"name": "Rezervacije hotela",
"key": "dtk_live_9f2c…",
"scopes": ["read", "rides", "book", "pricing"],
"expiresAt": null,
"allowedIps": ["203.0.113.10", "198.51.100.0/24"],
"createdAt": "2026-11-17T08:00:00.000Z"
}
Rotation and revocation
| Action | Route | What happens |
|---|---|---|
| List keys | GET /api/company/api-keys | Name, scopes, last use; the secret is not returned |
| Rotation | POST /api/company/api-keys/{id}/rotate | The same key (id, name, scopes) gets a new secret; the old one stops working immediately |
| Revocation | DELETE /api/company/api-keys/{id} | The key stops working; the record and delivery history remain |
Address allow-list
If the key has an address list, a request from another address returns 403 with errors.apiKeyIpNotAllowed. The address is taken from the connection source, not from a client-controlled header.
| Code | Status | Means |
|---|---|---|
errors.invalidApiKey | 401 | The key is not recognised (wrong, deleted or malformed) |
errors.apiKeyRevoked | 403 | The key was revoked |
errors.apiKeyExpired | 403 | The key expired |
errors.apiKeyIpNotAllowed | 403 | The request comes from an address not on the list |
errors.forbidden | 403 | The key lacks the required scope |
errors.moduleDisabled | 400 | The company does not have the addon.api_access module enabled |
errors.tenantInactive | 403 | The company is not active (trial expired, blocked) |
Keeping the key safe
- The key lives in server secrets (environment variable, cloud secret), never in code or a repository.
- One key per integration: when one stops, only its key is revoked.
- For writes (
book) use a separate key from the one that only reads. - If a key leaks, rotate it immediately — delivery history and the audit log show what happened before the rotation.

