Authentication
One scheme per API. The Partner Order API uses HMAC-SHA256 request signing — the same scheme Stripe uses for webhooks. You never send your secret over the wire; instead you sign each request with it and Betakom recomputes the signature to verify it. Your partnerId and secret are issued during onboarding (see Get Started). The Customs Clearance API uses a per-company API key instead — see Customer API keys below.
Request headers
Every signed request carries these three headers:
| Field | Type | Required | Description |
|---|---|---|---|
x-partner-id | string | required | Your public partner identifier (e.g. "acme"). Selects the credential — and therefore the environment — used to verify the signature. |
x-betakom-timestamp | string | required | Unix seconds at signing time. Must be within ±5 minutes of Betakom server time, otherwise the request is rejected (replay protection). |
x-betakom-signature | string | required | v1=<hex>, where <hex> = HMAC-SHA256(secret, "<timestamp>.<rawBody>"). The bare <hex> form (without the v1= prefix) is also accepted. |
How to sign a request
- Serialize the request body to a string (
payload). You must sign and send the exact same bytes — re-serializing JSON later will break the signature. - Take the current Unix time in seconds (
timestamp). - Compute
signature = HMAC-SHA256(secret, "<timestamp>.<payload>")and hex-encode it. - Send
x-partner-id,x-betakom-timestampandx-betakom-signature: v1=<hex>.
Node.js
import crypto from 'crypto';
const PARTNER_ID = 'acme';
const SECRET = process.env.BETAKOM_PARTNER_SECRET; // shared with Betakom
async function ingestOrder(body) {
const payload = JSON.stringify(body);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signed = `${timestamp}.${payload}`;
const signature = 'v1=' + crypto
.createHmac('sha256', SECRET)
.update(signed)
.digest('hex');
return fetch('https://betakom.de/api/v1/partners/orders/ingest', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-partner-id': PARTNER_ID,
'x-betakom-timestamp': timestamp,
'x-betakom-signature': signature,
},
body: payload, // sign and send the EXACT same bytes
});
}cURL
# 1. Build the body once and sign "<timestamp>.<body>"
TS=$(date +%s)
BODY='{"partnerOrderId":"PO-1001","customer":{"email":"kunde@example.com"},"loading":{"country":"DE","city":"Berlin","postalCode":"10115"},"unloading":{"country":"DE","city":"Muenchen","postalCode":"80331"},"vehicleType":"sprinter","totalPriceEur":480}'
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$BETAKOM_PARTNER_SECRET" | awk '{print $2}')
# 2. Send the same bytes you signed
curl -X POST 'https://betakom.de/api/v1/partners/orders/ingest' \
-H 'content-type: application/json' \
-H "x-partner-id: acme" \
-H "x-betakom-timestamp: $TS" \
-H "x-betakom-signature: v1=$SIG" \
-d "$BODY"Verification & errors
- Replay protection: the timestamp must be within ±5 minutes of Betakom server time, or the request is rejected with
401. - Signature mismatch / unknown partner: returns
401with a generic message (we don't reveal whether a partner exists or is inactive). - Body limits: the order-ingest endpoint caps bodies at 100 KB (
413) and rate-limits to 60 requests/minute per partner (429).
Customer API keys
The Customs Clearance API is for Betakom business customers and uses a simpler scheme: a per-company API key. The company owner creates keys in the customer dashboard under Customs › API; each key is shown exactly once. Send it as a bearer token on every request:
cURL
curl 'https://betakom.de/api/v1/customs/cases' \
-H "Authorization: Bearer bk_live_…"X-API-Key: bk_live_…is accepted as an alternative header.- A key acts with the rights of the owner who created it. It stops working when it is revoked in the dashboard or when that person is removed from the company account — answered with
401 api_key_invalid. - At most 120 requests per minute per key (
429withRetry-After). Keep keys server-side; never ship them in a browser or mobile app.