API-токены и OpenAPI

Выпуск токенов с ограниченными областями для скриптов, MCP и ботов, описание API в формате OpenAPI и коды отказов.

API-токен — доступ для MCP, Telegram-бота и своих скриптов вместо ключа инстанса. У токена есть области: он открывает только то, что вы ему выдали. Пароли, коды 2FA и выгрузка хранилища токену недоступны никогда; настройки, выпуск токенов и привязка устройств — тоже.

Выпуск

Настройки → Доступ → API-токены:

Подпись — чтобы потом узнать токен, например «Claude на ноутбуке».
Шаблон — готовый набор областей:

Шаблон	Области
MCP финблока	`fin:read`, `fin:write`
MCP Нетворка	`crm`
Telegram-бот	`telegram`, `banks`, `booking`, `assistant`, `fin:read`, `fin:write`
Только чтение	`fin:read`, `vault:read-meta`, `servers:read`

Срок — 30 дней, 90 дней, год или без срока.
«Выпустить». Токен (ocd_…) показывается один раз — скопируйте его сразу.

Отзыв — «Отозвать»: клиент с этим токеном сразу получит 401. Вернуть отозванный токен нельзя, только выпустить новый.

Использование и лимит

Кнопка с графиком в строке токена раскрывает его статистику за 30 дней: вызовы по дням (ошибки и отказы лимита — отдельным цветом), последний вызов — время, запрос и адрес, усечённый до сети (203.0.113.0/24), и самые частые запросы. Хранятся только счётчики по дням и шаблонам маршрутов (GET /api/fin/accounts/:id) — тела запросов, параметры и значения в адресе не сохраняются. Дни считаются по UTC, статистика живёт 90 дней.

У каждого токена есть лимит запросов в минуту — по умолчанию 300. Его можно поменять там же, в статистике токена: новый лимит действует сразу, перевыпускать токен не нужно. Сверх лимита API отвечает 429 token_rate_limited с заголовком Retry-After — сколько секунд подождать. Короткий всплеск до размера лимита проходит, дальше запросы пропускаются равномерно.

Области

Область	Что открывает
`fin:read`	финансы — чтение
`fin:write`	финансы — запись (включает чтение)
`vault:read-meta`	хранилище — только список, без секретов
`calendar`	календарь
`tasks`	задачи
`docs`	документы (без удаления)
`servers:read`	серверы — чтение
`telegram`	Telegram
`banks`	вход в банки — выдавайте только боту
`booking`	брони
`assistant`	ассистент — широкая область
`crm`	нетворк (контакты и лиды)
`health`	состояние инстанса

Описание API (OpenAPI)

Справочник API — страница /api-reference вашего инстанса (например, https://имя.me.rivo.day/api-reference), вход для неё не нужен: каждый маршрут с параметрами, примером тела и готовой командой curl, области токена, коды ошибок и лимиты. Ссылка на него есть и в дашборде — кнопка «Документация» в разделе API-токенов показывает краткое описание прямо там. Машиночитаемый файл — по адресу /api/openapi.json вашего инстанса (например, https://имя.me.rivo.day/api/openapi.json), вход для него не нужен. Формат — OpenAPI 3.1: файл импортируется в Swagger Editor, Postman или Insomnia.

В описании только то, что доступно токенам: служебные маршруты и вход туда не попадают, из хранилища — только список записей без секретов.

Запросы

export RIVO_URL=https://имя.me.rivo.day
export RIVO_TOKEN=ocd_…
curl -H "Authorization: Bearer $RIVO_TOKEN" "$RIVO_URL/api/fin/summary"

Примеры в справочнике пользуются этими же переменными. Отказ — JSON с полями statusCode, code и message: ветвитесь по code, текст message может меняться.

Ответ	Что значит
`401 device_revoked`	токен отозван или истёк
`403 scope_forbidden`	маршрут вне областей токена — выпустите токен с нужной областью
`409 time_busy`	календарь: время занято (запрос с `checkConflicts: true`), в ответе пересечения и свободные окна
`429 token_rate_limited`	превышен лимит токена — повторите через `Retry-After` секунд
`429 rate_limited`	слишком часто — повторите через `retryAfter` секунд

Полный список кодов (в том числе plan_locked, module_disabled, vault_e2e_strict) и лимиты — в справочнике API.

Публичная бронь работает без токена — см. Бронь и вебхуки. Подключить Claude к дашборду — MCP-сервер.