Sessions & Authentication

Authentication domain handles user login, session management, and API key operations.

Key Concepts

Session: Server-side state tied to a refresh token (UUID)
Access Token: Short-lived JWT for API requests
Refresh Token: Long-lived session identifier for token renewal
API Key: Credentials for programmatic access

Endpoints Overview

Endpoint	Method	Description
`/auth/login`	POST	Authenticate with credentials
`/auth/logout`	POST	Invalidate session
`/auth/refresh`	POST	Get new access token
`/auth/mfa/verify`	POST	Complete MFA challenge
`/auth/mfa/setup`	POST	Initialize MFA setup
`/auth/password/reset`	POST	Request password reset
`/auth/password/change`	POST	Change password
`/api-keys`	GET	List API keys
`/api-keys`	POST	Create API key
`/api-keys/{id}`	DELETE	Revoke API key

Session Flow

Login → [MFA if enabled] → Access Token + Session Token
                                   │
                                   ▼
                          Use Access Token in requests
                                   │
                                   ▼ (before expiry)
                          Refresh → New Access Token

MFA States

State	Description
Not Configured	MFA not set up
Setup Pending	TOTP secret generated, awaiting confirmation
Enabled	MFA required on login

API Key Permissions

API keys can have a subset of user permissions:

Permission	Allows
`read`	View data
`trade`	Place/cancel orders
`withdraw`	Initiate withdrawals
`deposit`	Generate deposit addresses

Sessions & Authentication

Key Concepts

Endpoints Overview

Session Flow

MFA States

API Key Permissions

Related Use Cases