# Ключі та дозволи
> Ключі 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/uk/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/uk/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/uk/groups.md): Групи компаній: яких компаній сягає ключ, заголовок Ocost-Business, перенаправлення за кодами документа, needs_company і файли в групі.
- [Ліміти та помилки](https://ocost.io/docs/uk/limits.md): Документи тарифу на місяць, обмеження частоти, розміри, помилки за RFC 9457, повторні спроби і де зберігаються дані.
- [Підключити асистента](https://ocost.io/docs/uk/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)
