Auth Flow

The 4rho API supports two authentication paths: HMAC API keys for programmatic access and OAuth 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

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 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 (requires manage:account)
POST /v1/wallets/link — Submit the signed message to link the wallet (requires manage:account)
GET /v1/wallets — List all linked wallets (requires read:account)
DELETE /v1/wallets/:id — Unlink a wallet (requires manage:account)
PUT /v1/wallets/:id/primary — Set a wallet as primary (requires manage: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

{
  "isAdmin": true,
  "role": "super_admin",
  "permissions": ["view_users", "manage_users", "view_aml", "manage_aml"],
  "mfa": {
    "enabled": true,
    "verified": true
  }
}

Field	Type	Description
`isAdmin`	bool	True when the user is an admin (any role).
`role`	string	One of `support`, `ops`, `risk`, `finance`, `super_admin`.
`permissions`	string[]	RBAC permissions granted to the user's role.
`mfa.enabled`	bool	Whether MFA is configured on the account.
`mfa.verified`	bool	Whether the current session has cleared MFA.