Ключі та дозволи

Кожен запит передає API-ключ вашої компанії в заголовку Authorization:

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

Ключі

Власник або бухгалтер створює ключі в Налаштуваннях › Розробникам. Ocost показує ключ один раз і зберігає лише його відбиток. Якщо ви втратили ключ, відкличте його і створіть новий.

Початок ключа, ocost_sk_<id>_, не є секретом. Налаштування перелічують ключі за ним, разом із їхніми дозволами й останнім використанням. Сканери секретів помічають префікс ocost_sk_ у витоку.

Ключ належить компанії, у якій його створено. Компанія має щонайбільше 10 активних ключів. Строк дії ключа також може закінчуватися в певну дату.

Увага

Зберігайте ключі на своєму сервері. Ніколи не вставляйте їх у браузер, мобільний застосунок чи журнал.

Компанії групи

Власник групи компаній може дати ключу інші компанії групи у Налаштуваннях › Розробникам. Тоді ключ сягає їх усіх, зокрема доданих пізніше, або вибраних. Задати їх може й підтримка Ocost. Кожну зміну видно в Налаштуваннях як візит Ocost.

GET /public/v1/businesses перелічує компанії, яких сягає ключ, спершу його власну. Це може запитати будь-який ключ.

Назвіть компанію запиту заголовком Ocost-Business з її ідентифікатором. Без нього запит діє у власній компанії ключа.

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"

Ключ і його секрет лишаються ті самі, коли змінюються його компанії. Компанію, якої він більше не сягає, Ocost відхиляє з наступного запиту. Так само компанію, що вийшла з групи.

Групи компаній пояснюють, як ключ сягає кількох компаній і куди потрапляють його файли.

Заміна ключа

  1. Створіть новий ключ із тими самими дозволами.
  2. Переведіть на нього своє ПЗ.
  3. Відкличте старий ключ. Ocost відхиляє його вже з наступного запиту.

Дозволи

Ключ може робити лише те, що дозволяють його дозволи. Налаштування › Розробникам позначає для нового ключа перші три.

ДозвілДозволяє
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, інструмент 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} та інструменти MCP, що читають записи
search:readGET /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:businessOcost-Business не є ідентифікатором компанії.
429 urn:ocost:key:rateЗабагато запитів або забагато неправильних ключів з однієї адреси. Зачекайте Retry-After секунд.
400Запит має заголовок Ocost-View…, який надсилає лише вебзастосунок Ocost.

Див. також