API Keys

Overview

API Keys provide programmatic access to the WinNova platform. Each key is associated with a user account and can be configured with specific permissions (scopes), IP restrictions, and rate limits.

Creating an API Key

Log in to WinNova
Navigate to Settings → API Keys
Click Create New Key
Select the required scopes
(Optional) Configure IP whitelist and rate limit
Save your API Secret — it is shown only once

Key Format

Field	Format	Example
API Key	`po_live_` + 32 hex chars	`po_live_1a2b3c4d5e6f7a8b9c0d1e2f`
API Secret	64 hex chars	`abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890`

Scopes

Scope	Description
`markets:read`	Query events, markets, and orderbooks
`orders:write`	Place bets and cancel limit orders
`orders:read`	View order details and history
`portfolio:read`	View positions and portfolio data
`ws:read`	Establish WebSocket connections
`points:write`	Write access to points/rewards
`copytrade:write`	Place copy-trade orders

Key Management

Maximum 10 active keys per user account
Keys can be revoked at any time (irreversible)
Optional expiration date — keys auto-expire after the set date
IP Whitelist — restrict key usage to specific IP addresses (supports CIDR notation)

Security Features

Feature	Description
HMAC-SHA256 signature	Every request carries a signature to prevent tampering
Timestamp window	±5 minutes — protects against replay attacks
Nonce deduplication	Same nonce rejected within a 7-minute window
IP Whitelist	Optional — supports IP and CIDR (no `/0` allowed), up to 20 entries
Rate limiting	Up to 1000 requests/minute (default 100); Redis fail-closed

Managing API Keys via REST

API Keys can also be managed programmatically using the User API (/api/v1). User API requests require a JWT token: Authorization: Bearer <jwt_token>.

Create a Key

POST /api/v1/apikeys

{
  "name": "my-trading-bot",
  "scopes": ["markets:read", "orders:write"],
  "ip_whitelist": ["1.2.3.4", "10.0.0.0/24"],
  "rate_limit": 200,
  "expires_at": "2026-12-31T23:59:59Z"
}

The api_secret is returned only once — save it immediately.

List Keys

GET /api/v1/apikeys

Get Key Details

GET /api/v1/apikeys/:id

Revoke a Key

DELETE /api/v1/apikeys/:id

Revocation is immediate and irreversible. The record remains with status: "revoked".

Security Best Practices

Never share your API Secret or commit it to version control
Use the minimum required scopes
Enable IP whitelist for production keys
Rotate keys periodically
Monitor last_used_at for suspicious activity

API Keys

On this page