Autentifikacija

Svaki zahtjev prema /api/v1/* mora sadržavati zaglavlje Authorization: Bearer <api-key>. Ključeve izdaju administratori tvrtke kroz locco web aplikaciju.

Bearer token model

locco koristi neprozirne (opaque) bearer tokene. Server pohranjuje ključ u hashiranom obliku, pa je njegova vrijednost u plaintextu vidljiva pozivatelju samo jednom (u trenutku izdavanja). Izgubljeni ključ ne može se vratiti. Umjesto toga, rotirajte ga.

Izdajte ključ pod Postavke → Integracije → API ključevi u locco web aplikaciji. Gumb “API dokumentacija” na toj stranici vodi ovamo.

Format ključa

Ključevi su nizovi oblika:

locco_live_<nasumicni-niz>

Prefiks locco_live_ je stabilan. Tretirajte ključ kao tajnu: spremite ga u svoj secret manager, nikada ga ne commitajte u verziju koda i nikada ga ne logirajte. Ključ daje pristup svakom endpointu na koji korisnik koji je izdao ključ ima dozvolu unutar ciljane tvrtke.

Zaglavlje X-Company-Id

Svaki zahtjev s API ključem MORA sadržavati Guid ciljane tvrtke u zaglavlju X-Company-Id:

X-Company-Id: 00000000-0000-0000-0000-000000000000

Nedostatak ovog zaglavlja vraća HTTP 400 s code: "VALIDATION_FAILED". Zaglavlje je obavezno u svakom zahtjevu, čak i kada vlasnik ključa pripada samo jednoj tvrtki. locco nikada ne zaključuje ciljani tenant samo iz ključa.

Pronađite Guid tvrtke u URL-u locco web aplikacije dok ste u ciljanoj tvrtki, ili ga zatražite od vlasnika računa.

Primjer zahtjeva

bash
curl https://api.locco.hr/api/v1/travel-entries \
  -H "Authorization: Bearer locco_live_..." \
  -H "X-Company-Id: 00000000-0000-0000-0000-000000000000"

Uspješni odgovori sadrže zaglavlja s ograničenjima zahtjeva (vidi Ograničenja zahtjeva) i standardno JSON tijelo. Odgovori s greškom sadrže stabilan strojno čitljiv code (vidi Greške).

Rotacija ključa

Za rotaciju ključa bez prekida rada:

  1. Generirajte novi ključ na stranici postavki. Odmah kopirajte plaintext vrijednost u svoj secret manager.
  2. Postavite svoje klijente s novim ključem paralelno sa starim.
  3. Kada se promet preusmjeri, opozovite stari ključ. Opozvani ključevi vraćaju HTTP 401.

Ne postoji operacija “regeneriraj” koja čuva staru vrijednost ključa. Uvijek izdajte novi ključ, migrirajte, pa opozovite stari.

Pravo korištenja

Ciljana tvrtka mora imati pretplatničku značajku ApiAccess, koja je uključena u Enterprise paketu i dostupna kao plaćeni dodatak na ostalim paketima. Zahtjevi prema tvrtki bez ove značajke vraćaju HTTP 402 s code: "API_ACCESS_NOT_ENABLED". Pogledajte Cijene i pravo korištenja za potpunu matricu po paketima i oblik odgovora.

Pogledajte katalog grešaka za potpuni popis strojno čitljivih kodova grešaka i odgovarajući partnerski odgovor za svaki od njih.