> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.useroot.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.useroot.com/_mcp/server.

# 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

| Audience | How to authenticate |
|----------|---------------------|
| **Create** session token (`POST /api/session-tokens/party`) | API key only (`x-api-key`) |
| **Use** session token on payment-method endpoints | `Authorization: Bearer <token>` |

Example when calling payee or payer payment-method APIs:

```plaintext
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.