Authentication

Two keys, two uses

Each device has two credentials in the dashboard (Settings → Merchant → Devices). Never mix them:

Key	Format	Used in
API Key	UUID4 (e.g. a1b2c3d4-0000-4000-8000-000000000000)	X-Device-Id header on every REST request.
Secret Key	Hexadecimal	Only to verify HMAC on incoming webhooks. Never sent in requests.

Required header

Every request to pos.b4bit.com/api/v1/* must include:

X-Device-Id: <tu-api-key>

cURL

curl -H "X-Device-Id: $B4BIT_API_KEY" \
https://pos.b4bit.com/api/v1/currencies

Node (undici)

import { fetch } from 'undici';

const res = await fetch('https://pos.b4bit.com/api/v1/currencies', {
headers: { 'X-Device-Id': process.env.B4BIT_API_KEY },
});

Python

import os, requests

res = requests.get(
  'https://pos.b4bit.com/api/v1/currencies',
  headers={'X-Device-Id': os.environ['B4BIT_API_KEY']},
)

PHP

$ch = curl_init('https://pos.b4bit.com/api/v1/currencies');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Device-Id: ' . getenv('B4BIT_API_KEY')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);

Caution

Note on Swagger: the original B4bit Pay Swagger declares securityDefinitions.Basic, but the backend does not use Basic Auth. Actual authentication uses the X-Device-Id header. The OpenAPI 3 we publish already fixes this mismatch.

Where the webhook is configured

The webhook URL (where B4bit Pay will send status-change notifications) is configured in the device’s notification_url field, not managed through the API. The signature is verified with the hexadecimal Secret Key — see webhook.

Security

Danger

• Do not commit the API Key or Secret Key to git.
• Do not expose them in the frontend (all requests must go through your backend).
• Do not log them.
• Rotate them if you suspect exposure (contact support@b4bit.com).

Authentication errors

• HTTP 403 — Missing or invalid X-Device-Id.
• HTTP 500 — Internal server error. Retry with exponential backoff.

See errors for the full list.