Authentication

Overview

Authentication is required to access private channels (orders, portfolio) and perform trading operations (create_order, cancel_order). The WebSocket API supports two authentication methods:

API Key Authentication - Using API key and signature
Access Token Authentication - Using OAuth/JWT access token

API Key Authentication

Step 1: Generate Signature

Create an HMAC SHA256 signature using your API secret:

const message = `${apiKey},${timestamp}`;
const signature = HmacSHA256(message, apiSecret);

Step 2: Send Authentication Message

{
  "op": "auth",
  "data": {
    "key": "your_api_key",
    "timestamp": "1234567890",
    "signature": "generated_signature"
  }
}

Parameters:

key (string, required) - Your API key
timestamp (integer, required) - Current Unix timestamp in seconds
signature (string, required) - HMAC SHA256 signature

Step 3: Receive Confirmation

On successful authentication:

{
  "channel": "auth",
  "type": "authenticated"
}

On failure:

{
  "channel": "auth",
  "type": "error",
  "message": "invalid auth access",
  "code": 401
}

Access Token Authentication

For applications using OAuth/JWT authentication:

{
  "op": "auth",
  "data": {
    "access_token": "your_jwt_token"
  }
}

The access token should be a valid JWT token obtained through the OAuth flow.

Example: Complete Authentication Flow

const crypto = require('crypto');
const WebSocket = require('ws');

const apiKey = 'your_api_key';
const apiSecret = 'your_api_secret';
const timestamp = Math.floor(Date.now() / 1000);

// Generate signature
const message = `${apiKey},${timestamp}`;
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(message)
  .digest('hex');

// Connect to WebSocket
const ws = new WebSocket('wss://ws.dev.mbhq.net/ws');

ws.on('open', () => {
  // Send authentication
  ws.send(JSON.stringify({
    op: 'auth',
    data: {
      key: apiKey,
      timestamp: timestamp,
      signature: signature
    }
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  console.log('Received:', message);

  if (message.type === 'authenticated') {
    console.log('Successfully authenticated!');

    // Now you can subscribe to private channels
    ws.send(JSON.stringify({
      op: 'sub',
      channel: 'orders'
    }));
  }
});

Development: Bypass Authentication

Warning: Bypass authentication only works on the internal WebSocket port (8082) and should only be used for local development and testing.

For testing on the internal port:

JSON format:

{
  "op": "auth",
  "data": {
    "key": "test_user_key",
    "timestamp": "0",
    "signature": ""
  }
}

Friendly format:

auth 1000004
auth test_user_key

When using bypass authentication:

timestamp must be 0
signature must be empty string
key can be either an API key or a user ID
Only works on ws://localhost:8082/ws (internal port)
Does NOT work on port 8080 (public port)

Example Session

# Connect to INTERNAL websocket port
wscat -c ws://localhost:8082/ws

# You'll see:
< {"type":"message","connection_id":"...","internal":true}

# Authenticate using friendly command
> auth 1000004

# Response:
< {"channel":"auth","type":"authenticated"}

# Subscribe to private channels
> sub portfolio
< {"channel":"portfolio","type":"subscribed"}
< {"channel":"portfolio","type":"snapshot","data":[...],"timestamp":"...","gsn":123}

Best Practices

Keep credentials secure - Never expose API keys or secrets in client-side code
Use recent timestamps - Timestamps should be within a reasonable time window
Regenerate signatures - Create a new signature for each connection
Handle authentication errors - Implement proper error handling and reconnection logic
Use read-only keys - For applications that only need to read data, use read-only API keys

Troubleshooting

"invalid auth access" Error

This error occurs when:

Invalid API key or secret
Incorrect signature calculation
Expired or invalid access token
Attempting bypass auth on public port (8080)

Connection Refused

Check that you're connecting to the correct endpoint:

Development: wss://ws.dev.mbhq.net/ws
Production: wss://ws.mbhq.net/ws
Local (public): ws://localhost:8080/ws
Local (internal): ws://localhost:8082/ws

Next Steps

Orders Channel - Subscribe to order updates
Portfolio Channel - Monitor account balances
Trading Operations - Create and cancel orders

Authentication

On this page