Driveoskatalog platforme

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.

Tajna se prikazuje jednomPuni ključ vidi se samo u odgovoru na stvaranje. Poslije se u konzoli vidi naziv, opsezi, zadnja upotreba i prvih nekoliko znakova. Izgubljena tajna se ne može pročitati — ključ se rotira.

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.

OpsegSkupinaŠto dopušta
readčitanjeProfil tvrtke, whoami, katalog usluga; uključen uz svaki drugi opseg
ridesčitanjePopis i detalj vožnji, povijest i tijek statusa
bookpisanjeStvaranje i otkazivanje vožnje; mijenja podatke tvrtke
vehiclesčitanjePopis vozila s registracijom, klasom i aktivnošću
driversčitanjePopis vozača s kodom, imenom i statusom
pricingčitanjeProcjena cijene preko POST /v1/quote
statsčitanjeDnevna statistika vožnji i prometa
webhooksnadzorZdravlje 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

POST/api/company/api-keys

Izdaje novi ključ za tvrtku iz sesije. Samo vlasnik (OWNER). Odgovor sadrži punu tajnu — jedini put kad je vidljiva.

PoljeTipObaveznoOpis
namestring (2–80)✓Naziv po kojem se ključ prepoznaje (npr. „Rezervacije hotela“)
scopesstring[]—Najviše 8 vrijednosti iz tablice opsega
expiresAtISO 8601—Trenutak prestanka valjanosti; prazno znači da ne istječe
allowedIpsstring[]—Do 20 točnih adresa ili CIDR raspona (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"
}

Rotacija i opoziv

RadnjaRutaŠto se dogodi
Popis ključevaGET /api/company/api-keysNaziv, opsezi, zadnja upotreba; tajna se ne vraća
RotacijaPOST /api/company/api-keys/{id}/rotateIsti ključ (id, naziv, opsezi) dobiva novu tajnu; stara prestaje vrijediti odmah
OpozivDELETE /api/company/api-keys/{id}Ključ prestaje vrijediti; zapis i povijest dostava ostaju
Rotirajte bez zastojaRotacija je trenutna, pa je redoslijed važan: izdajte novi ključ, prebacite integraciju, provjerite da radi, pa opozovite stari. Rotacija na istom ključu ruši staru tajnu u istoj sekundi.

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.

KodStatusZnači
errors.invalidApiKey401Ključ nije prepoznat (pogrešan, izbrisan ili krivog oblika)
errors.apiKeyRevoked403Ključ je opozvan
errors.apiKeyExpired403Ključu je istekao rok
errors.apiKeyIpNotAllowed403Zahtjev dolazi s adrese koje nema na popisu
errors.forbidden403Ključ nema potreban opseg
errors.moduleDisabled400Tvrtka nema uključen modul addon.api_access
errors.tenantInactive403Tvrtka 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.
Svjetla temaTamna tema
Tvrtka → Razvoj: API ključevi, webhookovi i primjeri poziva u konzoli.