Driveosplatform catalogue

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.

The secret is shown onceThe full key is visible only in the creation response. Afterwards the console shows the name, scopes, last use and the first few characters. A lost secret cannot be read — the key is rotated.

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.

ScopeGroupWhat it allows
readreadCompany profile, whoami, service catalogue; included with every other scope
ridesreadRide list and detail, history and status timeline
bookwriteCreate and cancel rides; changes company data
vehiclesreadVehicle list with plate, class and activity
driversreadDriver list with code, name and status
pricingreadPrice estimate via POST /v1/quote
statsreadDaily ride and revenue statistics
webhooksopsWebhook 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

POST/api/company/api-keys

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.

FieldTypeRequiredDescription
namestring (2–80)✓A name that identifies the key (e.g. “Hotel bookings”)
scopesstring[]—At most 8 values from the scope table
expiresAtISO 8601—The moment validity ends; empty means it never expires
allowedIpsstring[]—Up to 20 exact addresses or CIDR ranges (IPv4/IPv6)
json201 — odgovor (tajna je maskirana u ovoj dokumentaciji)
{
  "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

ActionRouteWhat happens
List keysGET /api/company/api-keysName, scopes, last use; the secret is not returned
RotationPOST /api/company/api-keys/{id}/rotateThe same key (id, name, scopes) gets a new secret; the old one stops working immediately
RevocationDELETE /api/company/api-keys/{id}The key stops working; the record and delivery history remain
Rotate without downtimeRotation is instant, so order matters: issue a new key, switch the integration over, verify it works, then revoke the old one. Rotating the same key breaks the old secret in the same second.

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.

CodeStatusMeans
errors.invalidApiKey401The key is not recognised (wrong, deleted or malformed)
errors.apiKeyRevoked403The key was revoked
errors.apiKeyExpired403The key expired
errors.apiKeyIpNotAllowed403The request comes from an address not on the list
errors.forbidden403The key lacks the required scope
errors.moduleDisabled400The company does not have the addon.api_access module enabled
errors.tenantInactive403The 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.
Light themeDark theme
Company → Developer: API keys, webhooks and call examples inside the console.