VORQ DocsAuth API
The session handshake routes, GET /auth/nonce and POST /auth/session.
The session handshake. See Authenticate with a wallet for a walkthrough and Authentication model for what a session does and does not grant.
GET /auth/nonce
Issue a single-use nonce for an address.
Auth: public · Index-backed: no
| Query | Meaning |
|---|---|
address | Required. The wallet address that will sign. |
Response 200
{ "nonce": "3f9c0e1d2a4b5c6d7e8f901a2b3c4d5e", "expires_at": 1786000000, "chain_id": 84532 }| Field | Meaning |
|---|---|
nonce | 32 hex characters. Valid for 300 seconds, once. |
expires_at | Unix seconds, a JSON number. |
chain_id | The chain id to put in the VorqSession domain. |
An address holds at most 16 live nonces; issuing another drops the oldest.
curl -s "https://api.vorq.co/auth/nonce?address=0x…"POST /auth/session
Exchange a signed nonce for a session token.
Auth: public · Index-backed: no
Request
{ "address": "0x…", "nonce": "3f9c…", "signature": "0x…", "role": "client" }| Field | Rule |
|---|---|
address | The address the nonce was issued to. |
nonce | The nonce from GET /auth/nonce. |
signature | The wallet's VorqSession signature over (address, nonce). |
role | client (default) or provider. A provider session binds the wallet's ProviderRegistry id. |
Response 200
{ "token": "vorq_sess_8c1f…", "expires_at": 1786086400, "provider_id": 7 }provider_id is present only for a provider session. expires_at and provider_id are JSON numbers. A session lasts 24 hours. An address holds at most 32 live sessions; creating another evicts the one closest to expiry.
Send the token as authorization: Bearer <token>. A missing, malformed or expired token answers 401 with code: "invalid_session".
Errors
| Status | code | Cause |
|---|---|---|
400 | null, param: "nonce" | Unknown, expired or already-used nonce. |
400 | null | A malformed field, or an unknown role. |
401 | invalid_signature | The signature is malformed or not from address, or address is not the one the nonce was issued to. |
403 | not_registered | role: "provider" for a wallet with no registry id. |
503 | chain_unreachable, relay_unavailable (provider_id_read) | The provider id could not be read from the chain. Retryable. |