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

← К разделу «HTTP API»

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

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

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

Передача Bearer

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/1.1 429 Too Many Requests
Retry-After: 17

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

3.0 KiB Raw Blame History