Skip to main content

​
Overview

Some Roxom API endpoints which access protected account’s data require authentication. You’ll be provided with an API key, a private key and the algorithm used to generate the keys pair. Each request to these endpoints must include your API Key and a private key’s signature to verify the request integrity. Currently, Roxom only supports RSA-2048 algorithm and PKCS#8-encoded private keys to authenticate protected endpoints.
Roxom DOES NOT store your private key. We DO only store your API Key ID and the public key associated with your private key in order to verify your requests.
Keep your API key and your private key secure and never expose them in client-side code or public repositories. If you lose your private key, you will need to generate a new API key and you will be provided with a new private key.

​
Authentication Method

Each request requires:
  1. API Key: Your API Key. Example: “xrxk_key_3437401edb0560e2de84efe7d34327c4” (the format may vary)
  2. Request Signature: A base64-encoded RSA signature of the payload using your private key. The payload must be hashed using the SHA-256 algorithm, and then the digest must be signed using your private key.

​
Required Headers

X-API-Key: your_api_key_here
X-API-Signature: base64_encoded_rsa_signature
Content-Type: application/json
With actual values: 
X-API-Key: xrxk_key_3437401edb0560e2de84efe7d34327c4
X-API-Signature: qWZsftLfICoJ0hPkuipsX9q0hsLJoSNNnZvBUdrg8tOSxuYwIfmoIZ4zRzyXLvW7HFj+TC0i8Dt35LY3tsYgd07QT3/A6Oi4CBpeUVSZULDCYcA38YX+uEKPs9/la44Ncq2iL75C2tfDls7wI1o5dd9skkyWgc9QXVMhwQKS0Pu4KPGAl7Zm30ZrKUFnDBSXMCg/Jx9kS7U/BVhHVK6C6zEB5OWdDCKdf7uvqEtJ/rKVSkMO9byeNWzMYRsnZnpyKdzVgZsGOcDa8JqtKm0CmxLqiHnufqUqdvCF6zwVuSUKvwgQrIv3NrJzSCqkUhStETpzWzsZixRS3MI8yHzUZg==

​
Payload Generation

The payload that you MUST hash to then sign is the string representation of the request HTTP method (in uppercase), path (including query parameters e.g. ?includeClosed=true), and body payload (if any), concatenated with a colon (:) as a separator. Every parameter MUST be hashed as it’s sent in the request. Body parameters must be alphabetically sorted by key and concatenated with an ampersand (&) as a separator.
Body parameters that are null MUST be excluded from the payload.

​
Examples

GET Request with no body: 
Payload: "GET:/api/v1/accounts/balance"
GET Request with query parameters and no body: 
Payload: "GET:/api/v1/orders?includeClosed=true"
POST Request with body: 
Body: {"symbol": "BTCUSDT", "qty": 100, "isBuy": true}
Payload: "POST:/api/v1/orders:isBuy=true&qty=100&symbol=BTCUSDT"
POST Request with body and query parameters: 
Body: {"symbol": "BTCUSDT", "qty": 100, "isBuy": true}
Payload: "POST:/api/v1/orders?anyQueryParam=true:isBuy=true&qty=100&symbol=BTCUSDT"

​
Example Request

The below command is assuming that you have your Roxom private key stored in a file named priv.pem: 
echo -n 'GET:/api/v1/orders' \
  | openssl dgst -sha256 -sign priv.pem \
  | openssl enc -base64 -A

qWZsftLfICoJ0hPkuipsX9q0hsLJoSNNnZvBUdrg8tOSxuYwIfmoIZ4zRzyXLvW7HFj+TC0i8Dt35LY3tsYgd07QT3/A6Oi4CBpeUVSZULDCYcA38YX+uEKPs9/la44Ncq2iL75C2tfDls7wI1o5dd9skkyWgc9QXVMhwQKS0Pu4KPGAl7Zm30ZrKUFnDBSXMCg/Jx9kS7U/BVhHVK6C6zEB5OWdDCKdf7uvqEtJ/rKVSkMO9byeNWzMYRsnZnpyKdzVgZsGOcDa8JqtKm0CmxLqiHnufqUqdvCF6zwVuSUKvwgQrIv3NrJzSCqkUhStETpzWzsZixRS3MI8yHzUZg==

# Generate signature first, then make request
curl -X GET "https://api.roxom.com/api/v1/accounts/balance" \
  -H "X-API-Key: xrxk_key_3437401edb0560e2de84efe7d34327c4" \
  -H "X-API-Signature: qWZsftLfICoJ0hPkuipsX9q0hsLJoSNNnZvBUdrg8tOSxuYwIfmoIZ4zRzyXLvW7HFj+TC0i8Dt35LY3tsYgd07QT3/A6Oi4CBpeUVSZULDCYcA38YX+uEKPs9/la44Ncq2iL75C2tfDls7wI1o5dd9skkyWgc9QXVMhwQKS0Pu4KPGAl7Zm30ZrKUFnDBSXMCg/Jx9kS7U/BVhHVK6C6zEB5OWdDCKdf7uvqEtJ/rKVSkMO9byeNWzMYRsnZnpyKdzVgZsGOcDa8JqtKm0CmxLqiHnufqUqdvCF6zwVuSUKvwgQrIv3NrJzSCqkUhStETpzWzsZixRS3MI8yHzUZg==" \
  -H "Content-Type: application/json"

​
Error Responses

If authentication fails, you will receive one of the following error responses:

​
Missing API Key

{
  "error": 400,
  "message": "Api key header not provided"
}

​
Missing Signature

{
  "error": 400,
  "message": "Signature header not provided"
}

​
Invalid API Key

{
  "error": 401,
  "message": "Unauthorized"
}

​
Invalid Signature

{
  "error": 401,
  "message": "Unauthorized"
}

​
Best Practices

Follow these security practices for API key management:
  • Use environment variables to store API keys and private keys
  • Never commit API keys and private keys to version control systems
  • Rotate API keys and private keys regularly as part of your security policy
  • Restrict API key access to only necessary team members
Compromised API keys can lead to unauthorized trading activity. Treat them like passwords.
Implement robust error handling for authentication failures:
  • Implement proper error handling for 401 responses
  • Log authentication failures for security monitoring
  • Have a strategy for API key rotation and seamless updates
  • Set up alerts for repeated authentication failures

​
Next Steps

Base URLs

Configure your application with the correct API endpoints
⌘I