API ključevi i opsezi
Ključ je poput lozinke za program: kome pripada, što smije i što se dogodi ako procuri.
Program se ne može prijaviti lozinkom kao čovjek — nema ruke za tipkovnicu i nema mobitel za drugi faktor. Zato dobije ključ: dugačak niz znakova koji pripada tvrtki i nosi točno određena prava.
Opsezi
Opseg je jedino što ključ smije. read je uvijek uključen uz svaki drugi opseg, pa ključ s rides može i dohvatiti profil tvrtke, ali ne može naručiti vožnju.
| Opseg | Skupina | Što dopušta |
|---|---|---|
read | čitanje | Profil tvrtke, whoami, katalog usluga; uključen uz svaki drugi opseg |
rides | čitanje | Popis i detalj vožnji, povijest i tijek statusa |
book | pisanje | Stvaranje i otkazivanje vožnje; mijenja podatke tvrtke |
vehicles | čitanje | Popis vozila s registracijom, klasom i aktivnošću |
drivers | čitanje | Popis vozača s kodom, imenom i statusom |
pricing | čitanje | Procjena cijene preko POST /v1/quote |
stats | čitanje | Dnevna statistika vožnji i prometa |
webhooks | nadzor | Zdravlje webhookova: krajnje točke, dostave i zadnji pokušaj |
Kad ključu nedostaje opseg, odgovor je 403 s kodom errors.forbidden — ne 401. Razlika je važna: 401 znači da ključ nije prepoznat, 403 da je prepoznat ali ne smije.
Izdavanje ključa
Izdaje novi ključ za tvrtku iz sesije. Samo vlasnik (OWNER). Odgovor sadrži punu tajnu — jedini put kad je vidljiva.
| Polje | Tip | Obavezno | Opis |
|---|---|---|---|
name | string (2–80) | ✓ | Naziv po kojem se ključ prepoznaje (npr. „Rezervacije hotela“) |
scopes | string[] | — | Najviše 8 vrijednosti iz tablice opsega |
expiresAt | ISO 8601 | — | Trenutak prestanka valjanosti; prazno znači da ne istječe |
allowedIps | string[] | — | Do 20 točnih adresa ili CIDR raspona (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"
}
Rotacija i opoziv
| Radnja | Ruta | Što se dogodi |
|---|---|---|
| Popis ključeva | GET /api/company/api-keys | Naziv, opsezi, zadnja upotreba; tajna se ne vraća |
| Rotacija | POST /api/company/api-keys/{id}/rotate | Isti ključ (id, naziv, opsezi) dobiva novu tajnu; stara prestaje vrijediti odmah |
| Opoziv | DELETE /api/company/api-keys/{id} | Ključ prestaje vrijediti; zapis i povijest dostava ostaju |
Ograničenje po adresi
Ako je uz ključ upisan popis adresa, zahtjev s druge adrese vraća 403 s kodom errors.apiKeyIpNotAllowed. Adresa se čita iz izvora veze, a ne iz zaglavlja koje klijent može namjestiti.
| Kod | Status | Znači |
|---|---|---|
errors.invalidApiKey | 401 | Ključ nije prepoznat (pogrešan, izbrisan ili krivog oblika) |
errors.apiKeyRevoked | 403 | Ključ je opozvan |
errors.apiKeyExpired | 403 | Ključu je istekao rok |
errors.apiKeyIpNotAllowed | 403 | Zahtjev dolazi s adrese koje nema na popisu |
errors.forbidden | 403 | Ključ nema potreban opseg |
errors.moduleDisabled | 400 | Tvrtka nema uključen modul addon.api_access |
errors.tenantInactive | 403 | Tvrtka nije aktivna (probni period istekao, blokada) |
Kako čuvati ključ
- Ključ stoji u tajnama poslužitelja (varijabla okoline, tajna u oblaku), nikad u kodu ni u repozitoriju.
- Jedan ključ za jednu integraciju: kad jedna prestane, opoziva se samo njezin ključ.
- Za pisanje (
book) koristite odvojeni ključ od onoga koji samo čita. - Ako ključ curi, rotirajte ga odmah — povijest dostava i revizija pokazuju što se dogodilo prije rotacije.

