Auth Flow
The 4rho API supports two authentication paths: HMAC API keys for programmatic access and OAuth/wallet login for browser-based sessions.
HMAC API Keys (Programmatic)
API keys are the recommended authentication method for bots, market makers, and automated trading systems.
Lifecycle
- Issuance — An admin creates a key via the dashboard, specifying scopes, rate limit tier, and optional IP allowlist
- Credentials — The API key, secret, and passphrase are displayed exactly once — store them securely
- Usage — Every request is signed with HMAC-SHA256 (see Authentication)
- Rotation — Keys can be rotated without downtime; the old key is revoked and new credentials are issued
- Revocation — Keys can be revoked immediately by an admin
Key Properties
| Property | Description |
|---|---|
| API Key | Public identifier, prefixed with 4rho_ |
| Secret | Used to derive the HMAC signing key |
| Passphrase | Sent as a header on every request |
| Scopes | Granular permissions (e.g., trade:orders) |
| Rate Limit Tier | standard (10/s), market_maker (100/s), premium (50/s) |
| IP Allowlist | Optional — restricts usage to specific IPs |
| Expiration | Optional — keys can have an expiry date |
OAuth Login (Browser)
For browser-based applications, 4rho supports OAuth through external providers.
Flow
GET /v1/auth/oauth/:provider— Redirects to the provider's consent page- Provider redirects back with an authorization code
POST /v1/auth/callback— Exchanges the code for a 4rho JWT- The JWT is returned as an HTTP-only cookie and in the response body
Token Lifecycle
| Endpoint | Description |
|---|---|
POST /v1/auth/refresh | Exchange a valid refresh token for new tokens |
POST /v1/auth/revoke | Revoke a specific refresh token |
POST /v1/auth/revoke-all | Revoke all sessions for the current user |
POST /v1/auth/logout | Clear session cookies and revoke tokens |
Token Details
- Access token — Short-lived JWT (~15 minutes), sent as
Authorization: Bearer {token}or via HTTP-only cookie - Refresh token — Longer-lived (~7 days), used to obtain new access tokens
- CSRF token — Required for admin mutation endpoints, obtained via
GET /admin/csrf-token
Wallet Login
For crypto-native users, 4rho supports direct wallet authentication via EIP-191 message signing.
Flow
GET /v1/auth/nonce— Get a one-time nonce for signing- User signs the nonce message with their wallet (MetaMask, WalletConnect, etc.)
POST /v1/auth/wallet/login— Submit the signed message to authenticate- JWTs are returned as with OAuth
Wallet Linking
Authenticated users can link additional wallets via the wallet management endpoints:
GET /v1/wallets/link/nonce— Get a nonce for the wallet to link (requiresmanage:account)POST /v1/wallets/link— Submit the signed message to link the wallet (requiresmanage:account)GET /v1/wallets— List all linked wallets (requiresread:account)DELETE /v1/wallets/:id— Unlink a wallet (requiresmanage:account)PUT /v1/wallets/:id/primary— Set a wallet as primary (requiresmanage:account)
MFA (Multi-Factor Authentication)
Users with manage:account scope can manage MFA:
| Endpoint | Scope | Description |
|---|---|---|
GET /v1/auth/mfa/status | read:account | Check MFA enrollment status |
POST /v1/auth/mfa/setup | manage:account | Begin TOTP enrollment |
POST /v1/auth/mfa/verify-setup | manage:account | Confirm TOTP code and enable |
POST /v1/auth/mfa/verify | manage:account | Verify a TOTP code |
POST /v1/auth/mfa/disable | manage:account | Disable MFA |
POST /v1/auth/mfa/recovery | manage:account | Use a recovery code |
Admin routes can require MFA by setting ADMIN_MFA_REQUIRED=true. When enabled, admin endpoints return 403 unless the user has verified MFA in the current session.
Admin Check
GET /v1/auth/is-admin
Scope: read:account
Check whether the authenticated user has admin privileges.
Response
{
"is_admin": true
}