Skip to main content
AgentFlow supports two login mechanisms: SIWE (any EVM wallet) and Telegram. Both result in the same JWT cookie session.

​
POST /auth/nonce

Request a SIWE nonce. The nonce binds the wallet’s signed message to a single login attempt and prevents replay. Auth: none.
​
address
string
required
EVM address that will sign. Lowercase 0x-prefixed.
curl -X POST https://api.agentflow.website/auth/nonce \
  -H "Content-Type: application/json" \
  -d '{ "address": "0xabc..." }'
Response 
{
  "nonce": "h4d0...",
  "message": "agentflow.website wants you to sign in with your Ethereum account: 0xabc...\n\nNonce: h4d0...",
  "expiresAt": "2026-04-25T10:35:00Z"
}
The nonce expires in 5 minutes. Use it once.

​
POST /auth/verify

Verify the SIWE signature and issue a session cookie. Auth: none.
​
address
string
required
Same address used in /auth/nonce.
​
message
string
required
The exact SIWE message returned by /auth/nonce.
​
signature
string
required
Hex-encoded signature from the wallet.
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..."
  }'
Response 
{
  "user": {
    "id": "usr_01HQ...",
    "address": "0xabc...",
    "displayName": "0xabc..."
  }
}
Plus a Set-Cookie: af_session=...; HttpOnly; Secure; SameSite=Lax.

​
POST /auth/telegram

Used by the Telegram bot to mint a session for a Telegram user. Public integrators do not call this directly.
​
initData
string
required
Telegram WebApp initData payload, validated against the bot token.
Response: same as /auth/verify, plus the linked Telegram identity in user.telegram.

​
POST /auth/access-code

Sign in or sign up via a one-time access code. Used in onboarding flows that bypass wallet/Telegram.
​
code
string
required
Single-use access code.

​
POST /auth/logout

Clear the session cookie. Auth: required. 
curl -X POST https://api.agentflow.website/auth/logout \
  -H "Cookie: af_session=..."
Returns 204 No Content.

​
Errors

CodeWhen
nonce_expiredNonce older than 5 minutes
nonce_usedNonce already verified
signature_invalidSignature does not match address
telegram_invalidinitData hash mismatch
code_invalidAccess code not found or used