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:
- Environment Variables
# .env (never commit this file)
BITXPAY_API_KEY=your_api_key
BITXPAY_PRIVATE_KEY=Ed25519:your_private_key- Secrets Manager
// 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);- Vault
// HashiCorp Vault example
const vault = require('node-vault')();
const { data } = await vault.read('secret/data/bitxpay');Key Rotation
Rotate your API keys regularly:
- Generate a new API key in the dashboard
- Update your application with the new key
- Verify the new key works correctly
- Revoke the old key
// 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:
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:
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.
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
| Risk | Mitigation |
|---|---|
| Keys in source code | Use environment variables |
| Keys in logs | Redact sensitive data |
| Keys in URLs | Use headers instead |
| Keys in browser | Keep keys server-side only |
Secure Transmission
- Always use HTTPS
- Verify SSL certificates
- Use TLS 1.2 or higher
// Ensure SSL verification is enabled
const https = require('https');
https.request({
hostname: 'api.bitxpay.com',
rejectUnauthorized: true // Default, but be explicit
});