REST API Authentication Guide: Key Preparations for WaaS Web3 API Integration

Understanding REST API Authentication Requirements

All REST private request headers must contain the following essential components:

• OK-ACCESS-KEY: Your unique API key string (generated through the Developer Portal interface)
• OK-ACCESS-SIGN: HMAC SHA256 hash value encoded in Base-64 (detailed signature process below)
• OK-ACCESS-TIMESTAMP: UTC timestamp of request initiation (e.g., 2020-12-08T09:08:57.715Z)
• OK-ACCESS-PASSPHRASE: The security phrase created during API key generation

Some endpoints may require additional headers:

• OK-ACCESS-PROJECT: Your project's unique identifier (found in Project Details)

👉 Learn more about API security best practices

The Signature Generation Process

Creating the OK-ACCESS-SIGN header involves:

1. String Composition: Combine timestamp + HTTP method + requestPath + body (for POST requests)
2. Encryption: Use HMAC SHA256 with your SecretKey
3. Encoding: Convert to Base64 format

Example Signature Formula:

sign=CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA256(
    timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC',
    SecretKey
  )
)

Key Components:

• timestamp: Matches OK-ACCESS-TIMESTAMP (ISO format)
• method: Uppercase HTTP method (GET/POST)
• requestPath: API endpoint path
• body: JSON string for POST requests (omit for GET requests)

Practical Implementation Guide

Using Postman for API Testing

Postman provides an excellent environment for API development and testing. Follow these steps:

1. Parameter Setup:

   • For GET requests: Add query parameters under the Params tab

   • Required headers:

     • OK-ACCESS-KEY
     • OK-ACCESS-PASSPHRASE
     • OK-ACCESS-PROJECT (when applicable)

2. Request Body Configuration:

   • For POST requests: Select raw > JSON format
   • Paste your JSON payload in the body section

3. Pre-request Scripts:

   • Generate signatures dynamically using provided scripts
   • Configure separately for GET/POST methods

👉 Download Postman for free

JavaScript Implementation Example

Here's a basic JavaScript implementation for API calls:

const crypto = require('crypto');

function generateSignature(timestamp, method, path, body, secret) {
  const prehash = timestamp + method.toUpperCase() + path + (body || '');
  return crypto
    .createHmac('sha256', secret)
    .update(prehash)
    .digest('base64');
}

// Example usage
const apiCall = {
  timestamp: new Date().toISOString(),
  method: 'GET',
  path: '/api/v5/account/balance',
  secretKey: 'your_secret_key_here'
};

FAQ Section

What happens if my timestamp is incorrect?

The API will reject requests with timestamps differing from server time by more than 30 seconds. Always synchronize with NTP servers for accuracy.

How often should I rotate my API keys?

For optimal security, rotate your API keys every 60-90 days or immediately if you suspect any compromise.

Can I reuse the same signature for multiple requests?

No, each request requires a unique signature generated with current timestamp and specific parameters.

Why is my POST request returning 403 errors?

Verify that:

1. Your content-type header is 'application/json'
2. The body is properly formatted JSON
3. Your signature includes the complete request body

How do I troubleshoot signature generation failures?

Check:

• String concatenation order (timestamp+method+path+body)
• Base64 encoding implementation
• Secret key accuracy (no extra spaces)

Where can I find example implementations?

The OKX developer portal provides complete code samples in multiple languages including Python, Java, and JavaScript.

This comprehensive guide ensures you have all necessary information for successful WaaS Web3 API integration while maintaining top security standards. For additional support, consult our developer documentation.