xpendB2B
Get started

Authentication

Long-lived API credentials for server-to-server calls; short-lived JWTs for the merchant console.

API credentials

Server-to-server merchant API calls use a Bearer credential. API credentials are created in the console or through the merchant platform API and are scoped to a merchant environment.

Authorization: Bearer key_id.plaintext_secret

Never expose secret keys client-side

API credentials grant full merchant scope. Always call Xpend from your backend.

Verify a credential

curl "$XPEND_BASE/v1/merchant/principal" \
  -H "Authorization: Bearer $XPEND_SECRET_KEY"

The response includes the merchant ID, environment, actor type, actor ID, and granted scopes for the authenticated principal.

Token login

POST /v1/merchant-auth/login exchanges merchant login credentials for an access token suitable for Bearer authentication.

Rotation & revocation

  • Rotate: issues a replacement secret (returned once) and revokes the prior one.
  • Revoke: invalidates the credential immediately.

IP allowlists

API credentials can optionally restrict which client IPs may authenticate. Configure allowed_ips at creation or update the allowlist later. An empty list means no restriction. Calls from other IPs return API_KEY_IP_NOT_ALLOWED (403).

Full security guide

See Security for IP/CIDR rules, email OTP step-up, payout authenticator enrollment, and error codes.

Console JWT

Email + password (optionally TOTP) issues a short-lived access JWT plus an HttpOnly refresh cookie. Refresh tokens are rotated on every use.

Ready to build?
Get an API key

Sandbox-only credentials, no card required.

Stuck on something?
Talk to a human

DevRel responds in office hours.

PreviousQuickstartNextSecurity