Authentication

Learn how to authenticate your API requests using API keys

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.

Authentication Method

Each request requires:

API Key: Your API Key. Example: “xrxk_key_3437401edb0560e2de84efe7d34327c4” (the format may vary)
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.

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

Store API Keys Securely

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

Handle Authentication Errors

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

Last modified on October 9, 2026