Klucze i uprawnienia
Każde żądanie niesie klucz API Twojej firmy w nagłówku Authorization:
Authorization: Bearer ocost_sk_<id>_<secret>curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY"import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());Klucze
- PrefiksSkanery sekretów wykrywają go przy wycieku.
- Publiczny identyfikatorNie jest tajny. Ustawienia wymieniają klucze po nim.
- SekretPokazany raz. Trzymaj go na swoim serwerze.
Authorization: Bearer ocost_sk_…- Każde żądanie
Ocost-Business: <id>- Spółka grupy, opcjonalnie
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.
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
-H "Ocost-Business: $COMPANY_ID"files = session.get(
"https://api.ocost.io/public/v1/files",
headers={"Ocost-Business": company_id},
timeout=15,
).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());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
- Utwórz nowy klucz z tymi samymi uprawnieniami.
- Przełącz na niego swoje oprogramowanie.
- 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.
| Uprawnienie | Pozwala na |
|---|---|
documents:write | POST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, narzędzie MCP send_file |
documents:read | GET /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:read | GET /public/v1/search i narzędzia wyszukiwania MCP |
figures:read | Narzędzia liczb MCP. Klucz z nim tworzy tylko właściciel. |
exports:write | Narzę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:invalid | Brak 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:scope | Klucz nie ma uprawnienia wymaganego przez trasę. |
403 urn:ocost:key:business | Klucz nie sięga spółki wskazanej w Ocost-Business. |
400 urn:ocost:key:business | Ocost-Business nie jest identyfikatorem spółki. |
429 urn:ocost:key:rate | Za 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. |