Auth

Sign-In With Ethereum и Telegram-логин. JWT-cookie сессия.

AgentFlow поддерживает два механизма входа: SIWE (любой EVM-кошелёк) и Telegram. Оба ведут к одной JWT-cookie сессии.

Для серверных и CI-сценариев, где cookie-сессия неудобна, см. API-ключи — долгоживущие bearer-токены, выпускаемые через /me/api-keys.

​

POST /auth/nonce

Запросить SIWE-nonce. Nonce связывает подписанное кошельком сообщение с одной попыткой входа и предотвращает replay.

Auth: нет.

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

EVM-адрес, который будет подписывать. В нижнем регистре с префиксом 0x.

curl

curl -X POST https://api.agentflow.website/auth/nonce \
  -H "Content-Type: application/json" \
  -d '{ "address": "0xabc..." }'

Ответ

{
  "nonce": "h4d0...",
  "message": "agentflow.website wants you to sign in with your Ethereum account: 0xabc...\n\nNonce: h4d0...",
  "expiresAt": "2026-04-25T10:35:00Z"
}

Nonce истекает через 5 минут. Используется один раз.

​

POST /auth/verify

Проверить SIWE-подпись и поставить сессионную cookie.

Auth: нет.

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

Тот же адрес, что использовался в /auth/nonce.

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

Точное SIWE-сообщение, возвращённое из /auth/nonce.

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

Hex-подпись из кошелька.

curl

curl -X POST https://api.agentflow.website/auth/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "address": "0xabc...",
    "message": "agentflow.website wants you to sign in...",
    "signature": "0x..."
  }'

Ответ

{
  "user": {
    "id": "usr_01HQ...",
    "address": "0xabc...",
    "displayName": "0xabc..."
  }
}

Плюс Set-Cookie: af_session=...; HttpOnly; Secure; SameSite=Lax.

​

POST /auth/telegram

Используется Telegram-ботом для выпуска сессии Telegram-пользователю. Публичные интеграторы напрямую не вызывают.

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

Telegram WebApp initData payload, проверенный против токена бота.

Ответ: тот же, что и у /auth/verify, плюс привязанная Telegram-идентичность в user.telegram.

​

POST /auth/access-code

Войти или зарегистрироваться по одноразовому коду доступа. Используется в onboarding-сценариях, обходящих кошелёк/Telegram.

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

Одноразовый код доступа.

​

POST /auth/logout

Очистить сессионную cookie. Auth: требуется.

curl -X POST https://api.agentflow.website/auth/logout \
  -H "Cookie: af_session=..."

Возвращает 204 No Content.

​

Ошибки

Код	Когда
nonce_expired	Nonce старше 5 минут
nonce_used	Nonce уже использован
signature_invalid	Подпись не сходится с адресом
telegram_invalid	Хеш initData не сходится
code_invalid	Код доступа не найден или использован