Autentizace

Každý požadavek na /api/v1/* musí obsahovat hlavičku Authorization: Bearer <api-key>. Klíče vydávají administrátoři společnosti prostřednictvím webové aplikace locco.

Bearer token model

locco používá opaque bearer tokeny. Server klíč v úložišti hashuje, takže plaintext hodnota je volajícímu viditelná pouze jednou (při vytvoření). Ztracený klíč nelze nijak obnovit. Místo toho proveďte rotaci.

Klíč vydáte v sekci Nastavení → Integrace → API klíče ve webové aplikaci locco. Tlačítko “API documentation” na této stránce odkazuje sem.

Formát klíče

Klíče jsou řetězce ve tvaru:

locco_live_<opaque-random-string>

Prefix locco_live_ je stabilní. S klíčem zacházejte jako s tajným údajem: uložte jej do svého secret manageru, nikdy jej necommitujte do verzovacího systému a nikdy jej nelogujte. Klíč uděluje přístup ke každému endpointu, ke kterému má vydávající uživatel oprávnění v cílové společnosti.

Hlavička X-Company-Id

Každý požadavek s API klíčem MUSÍ obsahovat Guid cílové společnosti v hlavičce X-Company-Id:

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

Chybějící hlavička vrací HTTP 400 s code: "VALIDATION_FAILED". Hlavička je vyžadována u každého požadavku, a to i v případě, že uživatel vlastnící klíč patří pouze do jedné společnosti. locco nikdy neodvozuje cílového tenanta pouze ze samotného klíče.

Guid společnosti najdete v URL adrese webové aplikace locco, když se nacházíte v cílové společnosti, nebo si jej vyžádejte od vlastníka vašeho účtu.

Příklad požadavku

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

Úspěšné odpovědi obsahují hlavičky pro rate-limit (viz Rate limity) a standardní JSON tělo. Chybové odpovědi obsahují stabilní, strojově čitelný code (viz Chyby).

Rotace klíčů

Pro rotaci klíče bez výpadku:

  1. Vygenerujte nový klíč na stránce nastavení. Okamžitě zkopírujte plaintext hodnotu do svého secret manageru.
  2. Nasaďte své klienty s novým klíčem paralelně se starým.
  3. Jakmile se provoz přesměruje, starý klíč revokujte. Revokované klíče vrací HTTP 401.

Neexistuje žádná operace “regenerate”, která by zachovala hodnotu starého klíče. Vždy vydejte nový klíč, proveďte migraci a poté starý klíč revokujte.

Oprávnění

Cílová společnost musí mít v rámci předplatného funkci ApiAccess, která je součástí tarifu Enterprise a je k dispozici jako placený doplněk u všech ostatních tarifů. Požadavky na společnost bez této funkce vrací HTTP 402 s code: "API_ACCESS_NOT_ENABLED". Úplnou matici pro jednotlivé tarify a strukturu odpovědi najdete v sekci Ceník a oprávnění.

Úplný seznam strojově čitelných chybových kódů a odpovídající reakci partnera na každý z nich najdete v katalogu chyb.