MagicTradeBot API Authentication & Access Control

MagicTradeBot implements secure token-based authentication using JWT (JSON Web Tokens) to protect its Management API. This ensures that only authorized bot instances and users can access trading services, data, and exchange-related operations.

🚀 Overview

The Management App requires all API requests to be authenticated using a valid JWT token. Tokens are generated using a secure secret key with HMAC SHA-256 (HS256) algorithm and must be sent in the Authorization header of each API request.

⚙️ Configuration

1. Set JWT Secret Key

In your appsettings.json (or environment variables), configure the JWT secret key used to sign tokens: 

{
  "JwtSettings": {
    "SecretKey": "YOUR_SECURE_RANDOM_SECRET_KEY", // Minimum 32 characters recommended
    "Issuer": "MagicTradeBot",
    "Audience": "MagicTradeBotClients",
    "TokenExpiryMinutes": 120
  }
}

Alternatively, for Docker or cloud-based deployments, you can use environment variables: 

JwtSettings__SecretKey=YOUR_SECURE_RANDOM_SECRET_KEY

2. Token Generation During Bot Launch

When a MagicTradeBot Bot Instance is launched, it prompts for authentication credentials (e.g., botId and authKey). These credentials are securely transmitted to the Management App's authentication endpoint.

If the credentials are valid, the Management App issues a signed JWT token. This token is stored by the bot instance and automatically attached to the Authorization header of all subsequent API calls. 

POST /api/auth/login

Request Body:
{
  "botId": "bot-eu-01",
  "authKey": "your-secure-auth-key"
}

Successful Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

After receiving the token, the bot instance continues its lifecycle operations (scanning, trading, updating status, etc.) by including the JWT in all API requests: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This ensures secure and authenticated communication between bot instances and the Management App.

🧩 Access Control & Role Management

  • Assign roles to JWT claims (e.g., role: "bot", "admin", or "viewer")
  • Restrict API endpoints using policies or filters (e.g., [Authorize(Roles = "admin")])
  • For bot-specific endpoints, verify token claims against botId or instanceId
  • Deny access if the token is expired, invalid, or tampered with

🧪 Sample API Call with JWT

GET /api/trade/symbols

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

✅ Best Practices

  • Use a long and secure secret key (≥256-bit) for HS256
  • Store secrets in environment variables or secure vaults (not in code)
  • Rotate JWT secret keys periodically
  • Set short token expiry (e.g., 1-2 hours) and require refresh tokens if needed
  • Enable HTTPS to prevent token sniffing during transmission
  • Log and alert on failed token validation attempts

🔐 Optional Enhancements

  • Implement Refresh Token mechanism for long-lived sessions
  • Use HMAC or HMAC + IP binding to prevent token reuse across servers
  • Support JWT Blacklist or Revocation after logout or compromise

📎 Related Topics