Authentication

Every Swappr API request is authenticated with a Bearer token issued from your dashboard.

API key format

sk_<env>_<32-char-secret>

• env — test (sandbox) or live (production)
• The first 12 characters (sk_test_xxxx or sk_live_xxxx) are the visible prefix; the rest is the secret.

The host is the same for both environments (api.swappr.me); we route to sandbox or live based on the key’s env prefix. Resources are env-isolated — a sandbox key can only see sandbox wallets, payouts, beneficiaries, etc. Trying to fetch a live resource id with a sandbox key returns 404, not 401.

Sending the token

Include the key in the Authorization header:

curl https://api.swappr.me/v1/payouts \
  -H "Authorization: Bearer sk_test_..."

fetch('https://api.swappr.me/v1/payouts', {
  headers: { 'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}` },
});

requests.get(
    'https://api.swappr.me/v1/payouts',
    headers={'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}"},
)

IP allowlist

Every API key requires at least one IP address in its allowlist. Requests from any other IP are rejected with 403 ip_not_allowed.

Add IPs from your dashboard:

• API & Webhooks → click the key row → Restrict IPs
• Supports IPv4 and IPv6 (including :: shorthand)
• Multiple IPs allowed; comma-separated entry

Permissions

API keys inherit permissions from the Owner that created them. Most keys can:

• Read all wallets, payouts, beneficiaries, reports
• Create payouts (single + bulk)
• Manage beneficiaries
• Manage webhook endpoints

Some endpoints require explicit permission grants:

• Additional permissions may apply to capabilities enabled on your account beyond standard B2B disbursement (Owner-only by default)

If a key lacks a required permission, the response is 403 permission_denied.

Rotating keys

Generate a new key from your dashboard, deploy it to your application, then revoke the old key. There’s no automatic grace window — old keys stop working immediately when revoked.

To roll the secret on the same key (rare; usually you create a new one), use Rotate. The rotated secret is shown once + the old secret keeps working for 60 minutes so you can deploy without downtime.

Revoking keys

From the dashboard, click Revoke on the key. All subsequent requests with that key will return 401 invalid_api_key.

Test vs. live

The sandbox environment uses simulated providers — payouts complete instantly with success/failure outcomes you control via the outcome field. No real money moves.

Live environment uses real upstream rails. Funds debit your wallet and dispatch to the recipient’s bank.

Use sandbox to integrate + test your error handling, then flip to live keys for production.

Errors