Authentication and API keys
Bearer API keys, scopes, IP allow-lists, expiry and rotation.
Send the key as a bearer token on every request:
GET /v1/balances HTTP/1.1
Host: api.banking.wirebloom.com
Authorization: Bearer wb_live_7Hk2cQab…
X-Tenant-Id: 0192a6f0-0000-7000-8000-0000000000c1Creating a key
A customer Owner or Admin creates keys in the web app (Settings → API keys) or with createApiKey (POST /v1/api-keys, an interactive-session operation, not part of the public API-key reference) from an interactive session; a fresh step-up verification (api_key.create) is required. The full key is shown once in the response (secret); WireBloom stores only its SHA-256 hash and a display prefix (wb_live_7Hk2cQab). Store it in your secrets manager; if it is lost, rotate or create a new one.
POST /v1/api-keys
{ "name": "ERP sync", "environment": "live",
"scopes": ["balances:read", "transactions:read", "payments:write"],
"ipAllowlist": ["203.0.113.0/24"], "expiresAt": "2027-09-30T00:00:00Z" }Scopes
A key reaches only the operations whose contract lists its scope (x-api-key-scopes, shown on every operation in the reference); anything else is 403 insufficient-scope.
| Scope | Grants |
|---|---|
balances:read | balances, balance details, holds, enabled currencies |
transactions:read | transactions, journal, exports and jobs, annotations and attachments (read) |
statements:read | statements and PDF confirmations |
recipients:read | recipients and field requirements |
recipients:write | create, edit, delete and verify recipients |
payments:read | payments, transfers, scheduled payments, mandates, collections, bulk payments, approvals, funds requests |
payments:write | create/submit/cancel payments, transfers, add money, scheduled payments, mandates, collections, bulk payments, funds requests |
exchanges:read | quotes, exchanges, forward contracts |
exchanges:write | quotes, exchanges, forward contracts and drawdowns |
webhooks:manage | integrator webhook endpoints and deliveries (Webhooks) |
Keys can never approve payments, manage people, settings, cards or API keys. Payments created with a key follow the same limits and approval tiers as the web app (a payment may wait in pending_approval for a human approver).
Restrictions
ipAllowlist(IPv4/IPv6 addresses or CIDR blocks, up to 20): requests from other addresses get403ip-not-allowed.expiresAt: after it the key is401invalid-api-key.- A key is bound to one customer: another
X-Tenant-Idis403tenant-forbidden. wb_test_keys work only in environments with the sandbox.
Rotation
rotateApiKey (POST /v1/api-keys/{id}/rotate, from an interactive session, optional { "gracePeriodHours": 24 }, default 24, max 168, 0 revokes the old key at once) returns a new key with the same settings; the old key keeps working until the end of the grace period. Deploy the new key, confirm traffic, then revoke the old one (revokeApiKey, DELETE /v1/api-keys/{id}, immediate). lastUsedAt on the key and the per-key usage in the console (Integration and usage) help confirm the switch. Rotation needs step-up api_key.create.