Authentication
API keys for bank server-to-server calls; short-lived bearer tokens for the cardholder portal.
Bank / Issuer — API key
All server-to-server bank calls authenticate with a single header. Keys are scoped to your bank account, carry an environment, and can be revoked without rotating anything else.
X-Wishbone-API-Key: wbk_live_<key_id>:<secret>X-Wishbone-API-KeystringREQUIREDPrefix wbk_live_ (production) or wbk_test_ (sandbox), followed by <key_id>:<secret>.
The key is a server secret. It must never ship in a mobile binary or browser bundle. To put the donation flow in your app, mint a short-lived embed token from your backend — see Mobile SDK.
Only the secret half is stored, bcrypt-hashed, so the full key is displayed exactly once at issuance. If you lose it, issue a new one and revoke the old; there is no recovery path.
Cardholder portal — bearer token
The cardholder-facing portal uses a different mechanism. A cardholder signs in via POST /v1/portal/auth/login and receives a signed access token plus a refresh token.
Authorization: Bearer <access_token>| Property | Value |
|---|---|
| Algorithm | HS256 |
| Access token lifetime | 60 minutes |
| Refresh token lifetime | 90 days, rotating |
| Reuse grace window | 45 seconds — a refresh token replayed inside this window is treated as a concurrent-tab race, not theft. Outside it, the whole token family is revoked. |
Portal tokens are cardholder-scoped and are never interchangeable with your bank API key. A bank backend should not be holding one.
Cardholder account linking
POST /v1/accounts/link accepts an optional redirect_uri, which puts the new account in pending_oauth and returns an authorization URL.
The hosted authorization server behind that URL is not yet available. Until it ships, link accounts without redirect_uri — the account is created active immediately. See environment status.