Authentication

All Merchant API requests use a secret Bearer token issued from the Developers console.

API keys

Pass your key on every request:

curl -X GET "https://api.bitstac.io/api/v1/merchant/ping" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Accept: application/json"

Format: bst_test_ or bst_live_ followed by 48 hex characters.
Plaintext is shown once on create — Bitstac stores only a hash.
Revoke compromised keys immediately in Developers → API Keys.

Scopes

Endpoints declare required scopes. Missing scope returns 403 with insufficient_scope. Ping requires a valid key but no scope.

customers:read
customers:write
balances:read (reserved — no routes yet)

IP allowlist

If you configure allowed IPs / CIDRs in Developers → Settings, requests from other addresses fail with ip_not_allowed. Leave the list empty to allow all IPs.

Common auth errors

invalid_api_key — missing, malformed, revoked, or wrong secret
merchant_api_disabled — Merchant API not enabled for the business
kyb_not_complete — live key used before business KYB is complete
ip_not_allowed — caller IP not on the allowlist
insufficient_scope — key lacks the required scope

Full error catalogue: Errors & rate limits.