Session Tokens API
The Session Tokens API mints short-lived JWTs so a frontend can manage payment methods for a specific payee or payer without exposing your server-side API key.
When to use session tokens
Use session tokens when a browser or mobile client needs to call payment-method endpoints on behalf of one party (for example, a payee linking a bank account in an embedded flow).
Mint the token from your backend with an API key, then pass the JWT to the client. The client authenticates payment-method requests with Bearer auth — not x-api-key.
Authentication
Example when calling payee or payer payment-method APIs:
Do not put session tokens in client-side code as long-lived secrets. They expire (see expires_in_seconds in the create response) and are scoped to one party.
Endpoints
Use POST /api/session-tokens/party for all new integrations. It supports both payees and payers and returns a single simplified scope (payee_manage or payer_manage).
POST /api/session-tokens (payee-only, granular scopes) is deprecated. It remains available for backward compatibility only — migrate to the party endpoint.
Scopes and allowed APIs
A session token can only call payment-method routes for the party embedded in the token (party_id / payee or payer id). Typical flows:
- Your server creates a payee or payer.
- Your server calls the Session Tokens API with that party’s id.
- The client uses the returned JWT as
Authorization: Bearer …against Payee Payment Methods or Payer Payment Methods endpoints.
See the Payment Methods API overview for payment-method types, verification, and defaults.
Security notes
- Create tokens only on a trusted server with your API key.
- Tokens are party-scoped and short-lived; treat them as credentials while valid.
- Revocation is supported server-side; expired or revoked tokens are rejected.