# Токены и безопасность API

← [К разделу «HTTP API»](README.md)

## Создание токена

1. В панели управления откройте **Документы → JSON API**.
2. Нажмите создание токена.
3. Укажите понятное имя интеграции.
4. Выберите минимально необходимые scopes.
5. При необходимости задайте срок действия.
6. Скопируйте секрет сразу: повторно он не показывается.

Для управления токенами требуется право `manage_document_api`.

## Передача Bearer

```http
Authorization: Bearer ave_...
Accept: application/json
```

Не передавайте токен в query string, HTML, публичный JavaScript или журнал
запросов. Секрет предназначен для server-to-server интеграции и хранится в
секретах окружения внешнего сервиса.

В БД система хранит только SHA-256 hash и короткий prefix. Восстановить
потерянный секрет нельзя: отзовите его и создайте новый.

## Scopes и права пользователя

| Scope | Разрешает |
| --- | --- |
| `documents:read` | GET по ID и alias. |
| `documents:write` | POST/PUT/PATCH. |
| `documents:*` | Чтение и запись. |

Scope не заменяет роли. Владелец токена должен оставаться активным пользователем
и иметь `view_documents` для чтения или `manage_documents` для записи. Роль
`admin` и `all_permissions` проходят эту проверку.

Если пользователя отключили, его роль потеряла право, токен истёк или отозван,
API отвечает `401 unauthorized`.

## Срок и отзыв

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

## Ограничение запросов

Каждый токен может выполнить до 120 API-запросов за 60 секунд. При превышении:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
```

Клиент должен дождаться количества секунд из `Retry-After`, затем повторить
запрос с backoff. Не переключайтесь между несколькими токенами для обхода
лимита.