API-ключи

Долгоживущие токены с rate-limit, FLOW spend-cap и аналитикой использования по каждому ключу.

API-ключи позволяют вызывать AgentFlow с серверов, CI-раннеров, скриптов и webhook-интеграций — без жонглирования SIWE / Telegram-сессиями. Это третий путь авторизации рядом с cookie и JWT: те же роуты, те же права, просто другой заголовок.

У каждого ключа свой биллинг: лимит запросов в минуту, опциональный кап по тратам FLOW за период (день / неделя / месяц / forever) и журнал каждого вызова. Это копия Activity page у OpenRouter — в FLOW вместо USD.

​

Формат ключа

72 символа: af_live_ плюс 64 hex (32 байта CSPRNG, 256 бит энтропии). На сервере хранится только HMAC-SHA256 хэш + 12-символьный display prefix. Сырой ключ показывается ровно один раз.

af_live_3f9a82b1c4e6d77a5b2c1d8e6f4a3b9c2d1e8f7a6b5c4d3e2f1a09b8c7d6e5f

​

Когда использовать API-ключ

• Бэкенд, которому нужно выписывать чеки, читать marketplace-агентов или дёргать /me/* от имени владельца.
• CI-пайплайн, публикующий агентов или гоняющий стрим-тесты сборки.
• Долгоживущий бот, для которого поддерживать SIWE-сессию неудобно.

Для браузерных сценариев предпочтительнее cookie af_session от POST /auth/verify — она HttpOnly и обновляется автоматически.

​

POST /me/api-keys — создать ключ

Auth: cookie / bearer / x-api-key.

name · string · обязательно

Название, 1–64 символа. Положите его в secret manager — будущему вам пригодится.

rate_limit_rpm · integer

Лимит запросов в минуту. По умолчанию 60. 0 — без лимита.

spend_limit_flow · string | number

Кап FLOW на период. Лучше передавать строкой ("100.5") — числа теряют точность дальше 6 знаков. Пропустите для отсутствия капа.

spend_period · string

Период — day, week, month или forever. По умолчанию month.

curl

curl -X POST https://api.agentflow.website/me/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "name": "ci-runner",
    "rate_limit_rpm": 120,
    "spend_limit_flow": "50",
    "spend_period": "month"
  }'

Ответ:

{
  "ok": true,
  "id": 42,
  "name": "ci-runner",
  "prefix": "af_live_3f9a",
  "key": "af_live_3f9a82b1...",
  "created_at": "2026-04-26T10:00:00Z",
  "warning": "Save this key now — it will not be shown again."
}

​

GET /me/api-keys — список активных ключей

Возвращается публичная форма — без хэша. Каждая запись несёт текущие лимиты и spend_period_used, чтобы прогресс-бары рисовались без второго запроса.

{
  "ok": true,
  "items": [
    {
      "id": 42,
      "name": "ci-runner",
      "prefix": "af_live_3f9a",
      "created_at": "2026-04-26T10:00:00Z",
      "last_used_at": "2026-04-26T11:23:45Z",
      "rate_limit_rpm": 120,
      "spend_limit_flow": "50.000000",
      "spend_period": "month",
      "spend_period_used": "12.345678",
      "spend_period_start": "2026-04-01T00:00:00Z"
    }
  ]
}

​

PATCH /me/api-keys/:id — править лимиты

Все поля опциональны — передавайте только то, что хотите изменить. Смена spend_period сбрасывает spend_period_used в 0, чтобы новый bucket стартовал с чистого листа.

curl -X PATCH https://api.agentflow.website/me/api-keys/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{ "rate_limit_rpm": 200, "spend_limit_flow": "100" }'

​

DELETE /me/api-keys/:id — отозвать

Soft-revoke: строка остаётся для audit-трейла (кто создал, когда последний раз использовался). Все следующие запросы с x-api-key отозванного ключа получают 401.

​

Заголовок авторизации

Сырой ключ в x-api-key для любого запроса, который иначе требует сессию:

curl https://api.agentflow.website/me \
  -H "x-api-key: af_live_3f9a82b1..."

Смешивание creds запрещено: если вы передали и x-api-key, и Authorization: Bearer …, и ключ невалидный — будет 401, даже если bearer сам по себе работал.

​

Rate limits

В каждом успешном ответе:

Header	Что значит
X-RateLimit-Limit	Текущее rate_limit_rpm.
X-RateLimit-Remaining	Сколько слотов осталось в текущем минутном окне.
X-RateLimit-Reset	ISO-время, когда окно сбросится.

При превышении — 429 Too Many Requests + Retry-After (в секундах) + body:

{ "ok": false, "error": "rate_limited", "retry_after_ms": 23456 }

Окно — скользящие 60 секунд на ключ, проверка атомарная против api_keys row, поэтому лимит держится одинаково по всем репликам. rate_limit_rpm = 0 отключает лимит совсем.

​

Spend limits

Каждый запрос также получает:

Header	Что значит
X-FLOW-Cost	FLOW списано за этот запрос (0 для бесплатных endpoint’ов).
X-FLOW-Period-Used	FLOW потрачено в текущем периоде.
X-FLOW-Period-Limit	Текущий cap (отсутствует если cap не задан).
X-FLOW-Period-Reset	ISO-время, когда период закроется.

Когда period_used >= spend_limit_flow API возвращает 402 Payment Required:

{
  "ok": false,
  "error": "spend_limit_exceeded",
  "period_used": "100.000000",
  "period_limit": "100.000000",
  "period_reset_at": "2026-05-01T00:00:00Z"
}

Восстановление автоматическое на границе периода — без ручного сброса, без cron’а. Аккумулятор обнуляется лениво на следующем оплачиваемом вызове после смены периода.

​

Журнал использования

Каждый запрос с x-api-key пишется в api_key_usage (best-effort, не блокирует ответ). Два endpoint’а отдают данные:

​

GET /me/api-keys/:id/usage?since=day|week|month|all

{
  "ok": true,
  "since": "2026-03-26T10:00:00Z",
  "total_calls": 1421,
  "total_flow_charged": "12.345678",
  "total_tokens_in": 123456,
  "total_tokens_out": 78901,
  "by_endpoint": [
    { "endpoint": "POST /agents/foo/call", "count": 800, "flow": "10.000000" },
    { "endpoint": "GET /me", "count": 600, "flow": "0.000000" }
  ],
  "by_model": [
    { "model": "claude-haiku-4-5", "count": 800, "tokens_in": 100000, "tokens_out": 60000, "flow": "10.000000" }
  ],
  "by_day": [
    { "day": "2026-04-25", "count": 120, "flow": "1.234567" }
  ]
}

​

GET /me/api-keys/:id/recent?limit=50

{
  "ok": true,
  "items": [
    {
      "id": 9001,
      "endpoint": "GET /me",
      "status_code": 200,
      "flow_charged": "0",
      "tokens_in": 0,
      "tokens_out": 0,
      "model": null,
      "duration_ms": 24,
      "created_at": "2026-04-26T11:23:45Z"
    }
  ]
}

limit ограничен сверху 200. Подходит для live tail / отладки. На странице кабинета (API Key detail) этот endpoint опрашивается для секции “Recent calls”.

​

Сравнение с OpenRouter

Если вы уже на OpenRouter — модель та же, отличается только единица:

OpenRouter	AgentFlow
API key c USD spend cap	API key c FLOW spend cap
Activity page (calls + cost)	/me/api-keys/:id/usage + UI кабинета
X-RateLimit-* headers	X-RateLimit-* headers (те же имена)
Per-model breakdown	by_model в /usage

Страница agentflow.website/account/api-keys рендерит весь activity surface — лимиты, stat-карточки, прогресс по периоду, дневной график, recent calls — никаких дополнительных запросов с вашей стороны.

​

UI кабинета

В кабинете есть вкладка “API Keys” для создания, просмотра и отзыва ключей. Per-key detail на /account/api-keys/:id показывает редактор лимитов и activity surface, описанные выше.

​

Ротация

С точки зрения учётки ключ — иммутабельный. Ротация:

1. apiKeys.create({ name: 'ci-runner-v2', … }).
2. Переключите конфиг сервиса на новый ключ. Оба работают параллельно.
3. apiKeys.revoke(<old-id>).

Между шагами 1–3 — ваш safety margin: старый ключ продолжает обновлять last_used_at, и вы видите, что весь трафик ушёл на новый, прежде чем выдёргивать вилку.

​

Чеклист безопасности

• Храните сырой ключ в env-переменных, секрет-менеджерах (1Password, AWS Secrets Manager, doppler) или зашифрованных CI-переменных. Никогда не коммитьте в git.
• В audit-вьюхах используйте prefix как идентификатор для пользователя — его безопасно показывать.
• Ставьте spend_limit_flow, даже если доверяете потребителю — это самый дешёвый blast-radius limit, какой можно настроить.
• Ротируйте по расписанию (раз в квартал — здравый дефолт) через create-then-revoke.
• Отзывайте сразу при подозрении на утечку — soft-revoke сохраняет audit-трейл и не оставляет атакующему пространства для манёвра.