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