Ключі та дозволи
Кожен запит передає API-ключ вашої компанії в заголовку 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());Ключі
- ПрефіксСканери секретів помічають його при витоку.
- Публічний idНе секретний. Налаштування показують ключі за ним.
- СекретПоказується один раз. Тримайте його на своєму сервері.
Authorization: Bearer ocost_sk_…- Кожен запит
Ocost-Business: <id>- Компанія групи, необов’язково
Власник або бухгалтер створює ключі в Налаштуваннях › Розробникам. Ocost показує ключ один раз і зберігає лише його відбиток. Якщо ви втратили ключ, відкличте його і створіть новий.
Початок ключа, ocost_sk_<id>_, не є секретом. Налаштування перелічують ключі за ним, разом із їхніми дозволами й останнім використанням. Сканери секретів помічають префікс ocost_sk_ у витоку.
Ключ належить компанії, у якій його створено. Компанія має щонайбільше 10 активних ключів. Строк дії ключа також може закінчуватися в певну дату.
Увага
Зберігайте ключі на своєму сервері. Ніколи не вставляйте їх у браузер, мобільний застосунок чи журнал.
Компанії групи
Власник групи компаній може дати ключу інші компанії групи у Налаштуваннях › Розробникам. Тоді ключ сягає їх усіх, зокрема доданих пізніше, або вибраних. Задати їх може й підтримка Ocost. Кожну зміну видно в Налаштуваннях як візит Ocost.
GET /public/v1/businesses перелічує компанії, яких сягає ключ, спершу його власну. Це може запитати будь-який ключ.
Назвіть компанію запиту заголовком Ocost-Business з її ідентифікатором. Без нього запит діє у власній компанії ключа.
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());Ключ і його секрет лишаються ті самі, коли змінюються його компанії. Компанію, якої він більше не сягає, Ocost відхиляє з наступного запиту. Так само компанію, що вийшла з групи.
Групи компаній пояснюють, як ключ сягає кількох компаній і куди потрапляють його файли.
Заміна ключа
- Створіть новий ключ із тими самими дозволами.
- Переведіть на нього своє ПЗ.
- Відкличте старий ключ. Ocost відхиляє його вже з наступного запиту.
Дозволи
Ключ може робити лише те, що дозволяють його дозволи. Налаштування › Розробникам позначає для нового ключа перші три.
| Дозвіл | Дозволяє |
|---|---|
documents:write | POST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, інструмент 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} та інструменти MCP, що читають записи |
search:read | GET /public/v1/search та пошукові інструменти MCP |
figures:read | Інструменти MCP для показників. Ключ із цим дозволом створює лише власник. |
exports:write | Інструменти MCP для експорту |
Інструменти MCP перелічує кожен інструмент під його дозволом.
Жоден ключ ніколи не читає особисті папери людей, як-от розрахункові листи, зарплатні чи медичні документи.
Відмови
| Відповідь | Коли |
|---|---|
401 urn:ocost:key:invalid | Немає ключа, або він неправильно сформований, неправильний, відкликаний чи прострочений, або належить видаленій компанії. Відповідь завжди однакова. |
403 urn:ocost:key:scope | Ключу бракує дозволу, потрібного маршруту. |
403 urn:ocost:key:business | Ключ не сягає компанії, яку називає Ocost-Business. |
400 urn:ocost:key:business | Ocost-Business не є ідентифікатором компанії. |
429 urn:ocost:key:rate | Забагато запитів або забагато неправильних ключів з однієї адреси. Зачекайте Retry-After секунд. |
400 | Запит має заголовок Ocost-View…, який надсилає лише вебзастосунок Ocost. |