Uwierzytelnianie

Każde żądanie do /api/v1/* musi zawierać nagłówek Authorization: Bearer <api-key>. Klucze są generowane przez administratorów firmy w aplikacji webowej locco.

Model tokenów bearer

locco używa nieprzejrzystych (opaque) tokenów bearer. Serwer haszuje klucz w spoczynku, więc wartość w postaci czystego tekstu jest widoczna dla wywołującego tylko raz (w momencie utworzenia). Nie ma możliwości odzyskania utraconego klucza. W takim przypadku należy przeprowadzić rotację.

Wygeneruj klucz w sekcji Ustawienia → Integracje → Klucze API w aplikacji webowej locco. Przycisk „Dokumentacja API” na tej stronie prowadzi tutaj.

Format klucza

Klucze są ciągami znaków o następującym formacie:

locco_live_<opaque-random-string>

Prefiks locco_live_ jest stały. Traktuj klucz jako poufny: przechowuj go w menedżerze sekretów (secret manager), nigdy nie dodawaj go do systemu kontroli wersji i nigdy nie zapisuj go w logach. Klucz daje dostęp do każdego endpointu, do którego uprawnienia ma użytkownik generujący klucz w docelowej firmie.

Nagłówek X-Company-Id

Każde żądanie z użyciem klucza API MUSI zawierać identyfikator Guid docelowej firmy w nagłówku X-Company-Id:

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

Brak nagłówka powoduje zwrócenie błędu HTTP 400 z kodem code: "VALIDATION_FAILED". Nagłówek jest wymagany przy każdym żądaniu, nawet jeśli użytkownik będący właścicielem klucza należy tylko do jednej firmy. locco nigdy nie wnioskuje docelowej firmy na podstawie samego klucza.

Znajdź identyfikator Guid firmy w adresie URL aplikacji webowej locco po przejściu do docelowej firmy lub poproś o niego właściciela konta.

Przykładowe żądanie

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

Pomyślne odpowiedzi zawierają nagłówki limitów zapytań (zobacz Limity zapytań) oraz standardową treść JSON. Odpowiedzi z błędami zawierają stały, czytelny dla maszyn kod code (zobacz Błędy).

Rotacja kluczy

Aby przeprowadzić rotację klucza bez przestojów:

  1. Wygeneruj nowy klucz na stronie ustawień. Natychmiast skopiuj jego wartość w postaci czystego tekstu do swojego menedżera sekretów (secret manager).
  2. Wdróż swoich klientów z nowym kluczem równolegle ze starym.
  3. Po przeniesieniu ruchu unieważnij stary klucz. Unieważnione klucze powodują zwrócenie błędu HTTP 401.

Nie istnieje operacja „ponownego wygenerowania” (regenerate), która zachowałaby wartość starego klucza. Zawsze wygeneruj nowy klucz, przeprowadź migrację, a następnie unieważnij stary.

Uprawnienia

Docelowa firma musi posiadać funkcję subskrypcji ApiAccess, która jest zawarta w planie Enterprise i dostępna jako płatny dodatek w każdym innym planie. Żądania do firmy bez tej funkcji zwracają błąd HTTP 402 z kodem code: "API_ACCESS_NOT_ENABLED". Zobacz Cennik i uprawnienia, aby zapoznać się z pełną macierzą planów i strukturą odpowiedzi.

Zobacz katalog błędów, aby zapoznać się z pełną listą maszynowo czytelnych kodów błędów i odpowiednimi reakcjami partnera na każdy z nich.