Klucze i uprawnienia

Każde żądanie niesie klucz API Twojej firmy w nagłówku Authorization:

Text
Authorization: Bearer ocost_sk_<id>_<secret>
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"

Klucze

Właściciel lub księgowy tworzy klucze w Ustawienia › Programiści. Ocost pokazuje klucz raz i zachowuje tylko jego odcisk. Jeśli zgubisz klucz, unieważnij go i utwórz nowy.

Początek klucza, ocost_sk_<id>_, nie jest tajny. Ustawienia wymieniają klucze według niego, z ich uprawnieniami i ostatnim użyciem. Skanery sekretów rozpoznają wyciek po prefiksie ocost_sk_.

Klucz należy do firmy, w której go utworzono. Firma ma najwyżej 10 aktywnych kluczy. Klucz może też wygasać w określonym dniu.

Ostrożnie

Trzymaj klucze na swoim serwerze. Nigdy nie umieszczaj klucza w przeglądarce, aplikacji mobilnej ani w logu.

Spółki grupy

Właściciel grupy spółek może dać kluczowi inne spółki grupy w Ustawienia › Programiści. Klucz sięga wtedy wszystkich, także dodanych później, albo wybranych. Może to też zrobić wsparcie Ocost. Każdą zmianę widać w Ustawieniach jako wizytę Ocost.

GET /public/v1/businesses wymienia spółki, do których sięga klucz, najpierw jego własną. Może o to zapytać każdy klucz.

Wskaż spółkę żądania nagłówkiem Ocost-Business z jej identyfikatorem. Bez niego żądanie działa we własnej firmie klucza.

Text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"

Klucz i jego sekret pozostają te same, gdy zmieniają się jego spółki. Spółkę, do której już nie sięga, Ocost odrzuca od następnego żądania. Tak samo spółkę, która opuściła grupę.

Grupy spółek wyjaśniają, jak klucz sięga kilku spółek i gdzie trafiają jego pliki.

Wymiana klucza

  1. Utwórz nowy klucz z tymi samymi uprawnieniami.
  2. Przełącz na niego swoje oprogramowanie.
  3. Unieważnij stary klucz. Ocost odrzuca go już od następnego żądania.

Uprawnienia

Klucz może robić tylko to, na co pozwalają jego uprawnienia. Ustawienia › Programiści zaznacza nowemu kluczowi pierwsze trzy.

UprawnieniePozwala na
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, narzędzie MCP send_file
documents:readGET /public/v1/files, GET /public/v1/files/{file_id}, GET /public/v1/files/{file_id}/content, GET /public/v1/files/{file_id}/document, GET /public/v1/documents/{document_id} i narzędzia MCP czytające rekordy
search:readGET /public/v1/search i narzędzia wyszukiwania MCP
figures:readNarzędzia liczb MCP. Klucz z nim tworzy tylko właściciel.
exports:writeNarzędzia eksportu MCP

Narzędzia MCP wymienia każde narzędzie pod jego uprawnieniem.

Żaden klucz nigdy nie czyta dokumentów pracowniczych, takich jak paski płacowe, listy płac czy dokumenty zdrowotne.

Odmowy

OdpowiedźKiedy
401 urn:ocost:key:invalidBrak klucza albo klucz zniekształcony, błędny, unieważniony, wygasły lub należący do usuniętej firmy. Odpowiedź jest zawsze taka sama.
403 urn:ocost:key:scopeKlucz nie ma uprawnienia wymaganego przez trasę.
403 urn:ocost:key:businessKlucz nie sięga spółki wskazanej w Ocost-Business.
400 urn:ocost:key:businessOcost-Business nie jest identyfikatorem spółki.
429 urn:ocost:key:rateZa dużo żądań albo za dużo błędnych kluczy z jednego adresu. Poczekaj Retry-After sekund.
400Żądanie ma nagłówek Ocost-View…, który wysyła tylko aplikacja webowa Ocost.

Zobacz też