Docs · Getting started

Authentication

Bearer token + HMAC signature + 5-minute timestamp tolerance.

Required headers

Authorization: Bearer lbk_<mode>_<key>
X-Timestamp: <unix-seconds> — must be within 300s of server time
X-Signature: v1=HMAC-SHA256(secret, canonical_request)
Idempotency-Key: <uuid> — required on mutating POST/PATCH/DELETE routes

Signing a request

Version v1 binds the timestamp, method, canonical path, sorted canonical query, idempotency key and exact body bytes. Generate the idempotency key before signing.

sign helper (bash)

TS=$(date +%s)
METHOD='POST'
REQUEST_PATH='/api/v1/accounts'
QUERY=''
IDEMPOTENCY_KEY=$(uuidgen)
BODY='{"marketplace":"leboncoin","credentials":{"email":"[email protected]","password":"replace-me"},"end_user_id":"customer-42"}'
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
IDEMPOTENCY_SHA256=$(printf '%s' "$IDEMPOTENCY_KEY" | openssl dgst -sha256 -hex | awk '{print $2}')
CANONICAL=$(printf 'listbridge-hmac-v1\ntimestamp:%s\nmethod:%s\npath:%s\nquery:%s\nidempotency-key-sha256:%s\nbody-sha256:%s' \
  "$TS" "$METHOD" "$REQUEST_PATH" "$QUERY" "$IDEMPOTENCY_SHA256" "$BODY_SHA256")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$HMAC_SECRET" -hex | awk '{print $2}')

curl -X "$METHOD" "https://api.listbridge.io$REQUEST_PATH" \
  -H "Authorization: Bearer lbk_live_xxx" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: v1=$SIG" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Canonical query encoding follows RFC 3986, treats + as a literal plus, preserves duplicate pairs and sorts by encoded key then value. The legacy sha256=timestamp.body contract is rejected.