# Ключи и права
> Ключи API: как запрос передаёт ключ, смена ключей, их права и отказы.

Каждый запрос передаёт API-ключ вашей компании в заголовке `Authorization`:

```text
Authorization: Bearer ocost_sk_<id>_<secret>
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
```

## Ключи

Владелец или бухгалтер создаёт ключи в разделе [Настройки › Разработчикам](https://app.ocost.io/settings/api). Ocost показывает ключ один раз и хранит только его отпечаток. Если вы потеряли ключ, отзовите его и создайте новый.

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

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

> [!WARNING]
> Храните ключи на своём сервере. Никогда не помещайте ключ в браузер, мобильное приложение или журнал.

## Компании группы

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

`GET /public/v1/businesses` перечисляет компании, до которых достаёт ключ, сначала его собственную. Это может спросить любой ключ.

Назовите компанию запроса заголовком `Ocost-Business` с её идентификатором. Без него запрос действует в собственной компании ключа.

```text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"
```

```python
files = session.get(
    "https://api.ocost.io/public/v1/files",
    headers={"Ocost-Business": company_id},
    timeout=15,
).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());
```

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

[Группы компаний](https://ocost.io/docs/ru/groups.md) объясняют, как ключ достаёт до нескольких компаний и куда попадают его файлы.

## Смена ключа

1. Создайте новый ключ с теми же правами.
2. Переключите на него своё ПО.
3. Отзовите старый ключ. 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](https://ocost.io/docs/ru/tools.md) каждый инструмент указан под своим правом.

Ни один ключ никогда не читает личные документы людей, например расчётные листки, данные о зарплате или медицинские документы.

## Отказы

| Ответ | Когда |
| --- | --- |
| `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. |

## См. также

- [Группы компаний](https://ocost.io/docs/ru/groups.md): Группы компаний: до каких компаний достаёт ключ, заголовок Ocost-Business, перенаправление по кодам документа, needs_company и файлы в группе.
- [Лимиты и ошибки](https://ocost.io/docs/ru/limits.md): Документы тарифа в месяц, лимиты частоты, размеры, ошибки RFC 9457, повторы и где хранятся данные.
- [Подключить ассистента](https://ocost.io/docs/ru/mcp.md): Подключить ассистента к серверу MCP (https://api.ocost.io/public/mcp, те же ключи): Claude Code, Claude Desktop, Cursor, claude.ai и ChatGPT через OAuth и любой клиент.
- На ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
