Autentifikácia

Každá požiadavka na /api/v1/* musí obsahovať hlavičku Authorization: Bearer <api-key>. Kľúče vydávajú administrátori spoločnosti prostredníctvom webovej aplikácie locco.

Bearer token model

locco používa opaque bearer tokeny. Server hashuje kľúč at rest, takže plaintext hodnota je pre volajúceho viditeľná iba raz (pri vytvorení). Stratený kľúč nie je možné nijako obnoviť. Namiesto toho ho rotujte.

Kľúč vydáte v sekcii Nastavenia → Integrácie → API kľúče vo webovej aplikácii locco. Tlačidlo “API documentation” na tejto stránke odkazuje sem.

Formát kľúča

Kľúče sú reťazce v tvare:

locco_live_<opaque-random-string>

Prefix locco_live_ je stabilný. S kľúčom zaobchádzajte ako s tajomstvom: uložte ho do svojho secret managera, nikdy nerobte jeho commit do správy verzií a nikdy ho nelogujte. Kľúč udeľuje prístup na každý endpoint, na ktorý má vydávajúci používateľ oprávnenie v cieľovej spoločnosti.

Hlavička X-Company-Id

Každá požiadavka s API kľúčom MUSÍ obsahovať Guid cieľovej spoločnosti v hlavičke X-Company-Id:

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

Chýbajúca hlavička vráti HTTP 400 s code: "VALIDATION_FAILED". Hlavička sa vyžaduje pri každej požiadavke, a to aj v prípade, že používateľ, ktorý vlastní kľúč, patrí iba do jednej spoločnosti. locco nikdy neodvodzuje cieľového tenanta len zo samotného kľúča.

Guid spoločnosti nájdete v URL adrese webovej aplikácie locco, keď sa nachádzate v cieľovej spoločnosti, alebo si ho vyžiadajte od vlastníka vášho účtu.

Príklad požiadavky

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

Úspešné odpovede obsahujú hlavičky pre rate-limit (pozrite si Rate limity) a štandardné JSON telo. Chybové odpovede obsahujú stabilný, strojovo čitateľný code (pozrite si Chyby).

Rotácia kľúčov

Ak chcete rotovať kľúč bez výpadku:

  1. Vygenerujte nový kľúč na stránke nastavení. Okamžite skopírujte plaintext hodnotu do vášho secret managera.
  2. Nasaďte svojich klientov s novým kľúčom paralelne so starým.
  3. Keď sa prevádzka presmeruje, revokujte starý kľúč. Revokované kľúče vracajú HTTP 401.

Neexistuje žiadna operácia “regenerate”, ktorá by zachovala hodnotu starého kľúča. Vždy vydajte nový kľúč, zmigrujte a následne revokujte ten starý.

Oprávnenia

Cieľová spoločnosť musí mať funkciu predplatného ApiAccess, ktorá je súčasťou plánu Enterprise a je k dispozícii ako platený doplnok v každej ďalšej úrovni. Požiadavky na spoločnosť bez tejto funkcie vracajú HTTP 402 s code: "API_ACCESS_NOT_ENABLED". Pozrite si Cenník a oprávnenia pre úplnú maticu podľa úrovní a štruktúru odpovede.

Pozrite si katalóg chýb pre úplný zoznam strojovo čitateľných chybových kódov a príslušnú reakciu partnera pre každý z nich.