> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WS token

> Mint a short-lived ws_token for browser/mobile websocket auth.

## Overview

`ws_token` is a short-lived JWT used to authenticate websocket streams from browser/mobile contexts without exposing long-lived API keys. It is not required for server-to-server connections that can send API key headers.

Note: `ws_token` is only for merchant/commerce streams. Payor streams use the payment session token.

## Authentication

Minting requires server-to-server auth:

* `x-api-key` (merchant)
* `x-commerce-api-key` (commerce)

## Request

Endpoint:

* `POST /api/v1/ws/token`

Playground (interactive reference):

* [Mint a WebSocket token](/api-spec/endpoints/ws-token-mint)

Example:

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/ws/token" \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"merchant"}'
```

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "merchant",
    "merchant_id": 123,
    "network_environment": null,
    "expires_at": 1766320496,
    "ws_url": "wss://api-beta.pepay.io/ws/merchant/events"
  }
}
```

## Errors

* `401` invalid API key
* `400` invalid scope/ttl

## Examples

* Use the returned `data.token` as `?token=<ws_token>` when connecting to `/ws/merchant/events` or `/ws/commerce/events` from browser/mobile clients.

Next: [WebSockets](/api-spec/realtime/websockets)