# Authentication & Environments

## Environments

| Environment | Base URL |
|  --- | --- |
| Sandbox | `https://api.banxa-sandbox.com` |
| Production | `https://api.banxa.com` |


Use sandbox for all development and testing. Production credentials are issued separately by Banxa after your integration has been approved.

Your partner reference (`{partnerRef}`) is a unique identifier assigned to your account. It is included in every API request path:


```
https://api.banxa-sandbox.com/{partnerRef}/v2/...
```

## API key authentication

All v2 endpoints use API key authentication. Include your API key in the request header:


```
x-api-key: YOUR_API_KEY
```

Your sandbox and production API keys are different. Retrieve them from the Partner Dashboard under your account settings.

## HMAC authentication

The identity token sharing endpoint (`POST /v2/identities/token/share`) requires HMAC-signed requests instead of the standard API key header.

HMAC is also used in the opposite direction for webhooks: Banxa signs every outbound webhook notification it sends to you, and you verify that signature to confirm it genuinely came from Banxa. The signing algorithm is the same, but the path in the canonical string is different — see [Webhooks](/products/hosted-checkout/docs/transaction-lifecycle/webhooks) for the verification flow.

HMAC credentials must be stored server-side. Never embed your API secret in frontend or mobile code.

### Authorization header


```
Authorization: Bearer API_KEY:SIGNATURE:NONCE
```

| Component | Description |
|  --- | --- |
| `API_KEY` | Your Banxa API key |
| `SIGNATURE` | Hex-encoded HMAC-SHA256 of the canonical string |
| `NONCE` | Unix timestamp in milliseconds, unique per request |


### Building the signature

Construct a newline-separated canonical string, then sign it with HMAC-SHA256 using your API secret.

**GET request:**


```
METHOD\nPATH_WITH_QUERY_STRING\nNONCE
```

**POST request:**


```
METHOD\nPATH\nNONCE\nCOMPACT_JSON_BODY
```

Rules:

- Use the request **path only** — never the full URL with domain
- Include the query string in the path for GET requests
- JSON body must be compact — no whitespace between elements
- Generate a new nonce for every request


### Code examples


```python
import hmac
import time
import json

key = '[YOUR_API_KEY]'
secret = '[YOUR_API_SECRET]'

def generate_hmac(method, path, payload=None):
    nonce = str(int(time.time() * 1000))
    parts = [method, path, nonce]
    if payload:
        parts.append(json.dumps(payload, separators=(',', ':')))
    data = '\n'.join(parts)
    signature = hmac.new(secret.encode('utf-8'), data.encode('utf-8'), 'sha256').hexdigest()
    return f'{key}:{signature}:{nonce}', nonce
```


```javascript
const crypto = require('crypto');

const key = '[YOUR_API_KEY]';
const secret = '[YOUR_API_SECRET]';

function generateHmac(method, path, payload = null) {
    const nonce = Date.now().toString();
    const parts = [method, path, nonce];
    if (payload) parts.push(JSON.stringify(payload));
    const data = parts.join('\n');
    const signature = crypto.createHmac('sha256', secret).update(data).digest('hex');
    return `${key}:${signature}:${nonce}`;
}
```


```php
<?php
$key = '[YOUR_API_KEY]';
$secret = '[YOUR_API_SECRET]';

function generateHmac($method, $path, $payload, $key, $secret) {
    $nonce = (string)(time() * 1000);
    $parts = [$method, $path, $nonce];
    if ($payload) $parts[] = $payload;
    $data = implode("\n", $parts);
    $signature = hash_hmac('sha256', $data, $secret);
    return "{$key}:{$signature}:{$nonce}";
}
```


```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Formatter;

public class BanxaAuth {
    private static final String KEY = "[YOUR_API_KEY]";
    private static final String SECRET = "[YOUR_API_SECRET]";

    public String generateHmac(String method, String path, String payload) throws Exception {
        String nonce = String.valueOf(System.currentTimeMillis());
        String data = method + "\n" + path + "\n" + nonce;
        if (payload != null) data += "\n" + payload;

        SecretKeySpec signingKey = new SecretKeySpec(SECRET.getBytes(), "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(signingKey);
        Formatter formatter = new Formatter();
        for (byte b : mac.doFinal(data.getBytes())) {
            formatter.format("%02x", b);
        }
        return KEY + ":" + formatter.toString() + ":" + nonce;
    }
}
```


```swift
import CryptoKit

let key = "[YOUR_API_KEY]"
let secret = "[YOUR_API_SECRET]"

func generateHmac(method: String, path: String, payload: String? = nil) -> String {
    let nonce = String(Int(Date().timeIntervalSince1970 * 1000))
    var parts = [method, path, nonce]
    if let payload = payload { parts.append(payload) }
    let data = parts.joined(separator: "\n")
    let secretKey = SymmetricKey(data: secret.data(using: .utf8)!)
    let signature = HMAC<SHA256>.authenticationCode(for: data.data(using: .utf8)!, using: secretKey)
        .map { String(format: "%02hhx", $0) }.joined()
    return "\(key):\(signature):\(nonce)"
}
```


```ruby
require 'openssl'

KEY = '[YOUR_API_KEY]'
SECRET = '[YOUR_API_SECRET]'

def generate_hmac(method, path, payload = nil)
    nonce = (Time.now.to_f * 1000).to_i.to_s
    parts = [method, path, nonce]
    parts << payload if payload
    data = parts.join("\n")
    signature = OpenSSL::HMAC.hexdigest('sha256', SECRET, data)
    "#{KEY}:#{signature}:#{nonce}"
end
```

### HMAC error codes

| Code | Cause |
|  --- | --- |
| `40001` | Nonce is not a valid Unix timestamp in milliseconds |
| `40002` | Nonce is too old — check your system clock is in sync |
| `40003` | Nonce already used — generate a new nonce per request |
| `40100` | API key not recognised — check you are using the correct environment key |
| `40101` | Authorization header is malformed — format must be `Bearer API_KEY:SIGNATURE:NONCE` |
| `40102` | Authorization header is missing |
| `40103` | Signature mismatch — check path, newline separators, compact JSON, and correct secret |


### Best practices

- Generate a **new nonce for every request** — reuse will be rejected
- Keep your system clock in sync (NTP) to avoid nonce expiry errors
- Serialize request bodies with **no whitespace** before signing
- Sign the **request path only** — never the full URL including domain
- Store your API secret in a secure secret store, never in source code or client-side storage
- Rotate your secret immediately if you suspect it has been exposed


## Rate limiting

The API is rate-limited to **500 requests per minute** across all endpoints combined, per IP address. Requests exceeding this limit will receive an HTTP `429 Too Many Requests` response.

**Best practices:**

- Use webhooks for order status updates instead of polling the orders endpoint.
- Call the quotes endpoint only when a customer actively requests a quote — do not poll for price feeds.
- Implement exponential backoff when retrying after a `429` response.
- If you consistently hit rate limits in normal operation, review your call patterns — it typically indicates unnecessary polling.


## Environment switching

Switch between sandbox and production via the environment toggle at the top of the Partner Dashboard. Configuration changes (webhooks, supported assets, UI settings) are made independently per environment.