Ключи и права

Каждый запрос передаёт 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.

См. также