Skip to content

Authentication Security ​

Proper authentication is critical for securing your BITXpay integration. This guide covers how to securely manage your API credentials.

API Key Management ​

Storing Credentials ​

Never hardcode credentials

Never store API keys directly in your source code.

Recommended approaches:

  1. Environment Variables
bash
# .env (never commit this file)
BITXPAY_API_KEY=your_api_key
BITXPAY_PRIVATE_KEY=Ed25519:your_private_key
  1. Secrets Manager
javascript
// AWS Secrets Manager example
import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManager({ region: 'us-east-1' });
const secret = await client.getSecretValue({ SecretId: 'bitxpay-credentials' });
const credentials = JSON.parse(secret.SecretString);
  1. Vault
javascript
// HashiCorp Vault example
const vault = require('node-vault')();
const { data } = await vault.read('secret/data/bitxpay');

Key Rotation ​

Rotate your API keys regularly:

  1. Generate a new API key in the dashboard
  2. Update your application with the new key
  3. Verify the new key works correctly
  4. Revoke the old key
javascript
// Support multiple keys during rotation
const apiKeys = [
  process.env.BITXPAY_API_KEY_NEW,
  process.env.BITXPAY_API_KEY_OLD
];

Request Signing ​

Signature Generation ​

Merchant API requests are signed with your Ed25519 (EdDSA) private key — not HMAC. Always generate signatures server-side. Note the canonical message order is METHOD + PATH + TIMESTAMP + BODY:

javascript
import crypto from 'crypto';

// privateKey: crypto.createPrivateKey({ key: Buffer.from(issued.slice(8), 'base64'), format: 'der', type: 'pkcs8' })
// where `issued` is the "Ed25519:..." string from the dashboard.
function signRequest(privateKey, method, path, timestamp, body = '') {
  // path must be the full request path, e.g. '/api/v1/payment_links'
  const message = `${method}${path}${timestamp}${body}`;

  // Ed25519 (EdDSA): pass `null` — Ed25519 hashes the message internally.
  const signature = crypto.sign(null, Buffer.from(message, 'utf8'), privateKey);

  return signature.toString('base64');
}

HMAC is for webhooks only

HMAC-SHA256 is used to verify inbound webhooks (see below), not to sign your outbound API requests. Don't confuse the two: outbound requests use the Ed25519 signature above. For the full signing guide, see Authentication.

Timestamp Validation ​

Include a current timestamp and handle clock skew:

javascript
const timestamp = new Date().toISOString(); // RFC 3339 string, not a Unix epoch

// Requests more than 5 minutes from server time (either direction) are rejected
// Ensure your server's clock is synchronized (use NTP)

Webhook Verification ​

Verify X-Webhook-Signature: sha256=<hex> over the exact raw request body, then parse the event. Reject missing or malformed signatures before comparison.

javascript
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.WEBHOOK_SECRET;
if (!secret) throw new Error('WEBHOOK_SECRET is required');

export function verifyWebhook(rawBody, signature, webhookSecret) {
  if (typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/.test(signature)) {
    return false;
  }
  const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest();
  return crypto.timingSafeEqual(Buffer.from(signature.slice(7), 'hex'), expected);
}

// Register before express.json() middleware to preserve the signed bytes.
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyWebhook(req.body, req.headers['x-webhook-signature'], secret)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body.toString('utf8'));
  console.log('Webhook:', event.event_type, event.data);
  // Durably enqueue the verified event before acknowledging it.
  // Apply business changes idempotently using payment/transaction references
  // in event.data: delivery id changes on retry; event_id identifies a type.
  res.sendStatus(200);
});

app.listen(3000);

See the Webhooks Guide for the delivery envelope and duplicate handling.

IP Whitelisting ​

Coming Soon

IP whitelisting is not yet available. This section describes planned functionality and will be updated once the feature ships.

For additional security, you will be able to whitelist your server IPs from the Dashboard → Settings → Security page, restricting API access to a set of known server IP addresses.

Common Vulnerabilities ​

Prevent Key Exposure ​

RiskMitigation
Keys in source codeUse environment variables
Keys in logsRedact sensitive data
Keys in URLsUse headers instead
Keys in browserKeep keys server-side only

Secure Transmission ​

  • Always use HTTPS
  • Verify SSL certificates
  • Use TLS 1.2 or higher
javascript
// Ensure SSL verification is enabled
const https = require('https');

https.request({
  hostname: 'api.bitxpay.com',
  rejectUnauthorized: true // Default, but be explicit
});