> ## 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.

# Authentication

> Auth headers and when to use each auth mode.

## Overview

Pepay supports multiple auth modes depending on the surface area (merchant, commerce, payor/session) and whether the request is **server-side** or **browser-side**.

If you’re getting started, log in to the Dashboard to obtain API keys: [https://pepay.io/sign-in](https://pepay.io/sign-in).

## Authentication

### Server-to-server (merchant + commerce)

* Merchant API key: `x-api-key: pk_...` (scope=merchant)
* Commerce API key: `x-commerce-api-key: ck_...` (scope=commerce)
* Dashboard JWT (for key-management endpoints): `Authorization: Bearer <jwt>`

### Browser-safe (payor/session)

Payor session endpoints use:

* `x-session-token: pst_...`
* `x-signature: sig_...`

### WebSocket auth (browser/mobile)

For websocket streams in client contexts, mint a short-lived `ws_token` **server-to-server**:

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

Then connect using:

* `wss://.../ws/merchant/events?token=<ws_token>`
* `wss://.../ws/commerce/events?token=<ws_token>`

## Request

Example (merchant API key):

```bash theme={null}
# Set your API URL (default: https://api-beta.pepay.io)
export PEPAY_API_URL="https://api-beta.pepay.io"

curl "${PEPAY_API_URL}/api/v1/invoices?limit=1" \
  -H "x-api-key: pk_..."
```

Example (payor/session headers):

```bash theme={null}
curl "${PEPAY_API_URL}/api/v1/payments/payment-status?invoice_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-session-token: pst_..." \
  -H "x-signature: sig_..."
```

Example (mint a ws\_token):

```bash theme={null}
curl -X POST "${PEPAY_API_URL}/api/v1/ws/token" \
  -H "x-api-key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"merchant"}'
```

## Response

Authentication is not a standalone endpoint — response shapes depend on the route you call. Below is a representative success response from `POST /api/v1/ws/token`.

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

Common causes:

* `401` missing or invalid credentials
* `403` wrong auth mode for the endpoint (for example, using `x-api-key` where `x-session-token` is required)
* `400` invalid signatures or invalid request bodies

Example (invalid API key):

```json theme={null}
{
  "success": false,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid API key"
  }
}
```

## Examples

* Do **not** send `x-api-key` or `x-commerce-api-key` from browsers.
* If you need client-side access, use payment sessions (`x-session-token` + `x-signature`) or mint a `ws_token` server-side.

Next: [Rate limits](/api-spec/rate-limits)