Skip to navigation

Session Tokens API

View as Markdown

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

AudienceHow to authenticate
Create session token (POST /api/session-tokens/party)API key only (x-api-key)
Use session token on payment-method endpointsAuthorization: Bearer <token>

Example when calling payee or payer payment-method APIs:

Authorization: Bearer <session_token>

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:

  1. Your server creates a payee or payer.
  2. Your server calls the Session Tokens API with that party’s id.
  3. 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.