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

# Configure

> Configure auth, base URLs, retries, and runtime adapters.

## Overview

The SDK is configured once and exposes resource groups (invoices, tokens, commerce, events, websockets, etc.).

## Authentication

The SDK supports multiple auth contexts (set once or per request). Choose the minimum required for your surface:

* `apiKey` → `x-api-key` (merchant scope)
* `commerceApiKey` → `x-commerce-api-key` (commerce scope)
* `bearerToken` → `Authorization: Bearer ...` (dashboard JWT)
* `userAccessToken` → `User-Authorization: Bearer ...` (commerce user routes)
* `sessionToken` + `signature` → `x-session-token` + `x-signature` (payor/session browser-safe)

## Request

### Construct a client

```ts theme={null}
import { Pepay } from 'pepay';

const pepay = new Pepay({
  baseUrl: process.env.PEPAY_API_URL ?? 'https://api-beta.pepay.io',
  apiKey: process.env.PEPAY_API_KEY
});
```

### Switch auth context

```ts theme={null}
const merchant = pepay.withAuth({ apiKey: process.env.PEPAY_API_KEY! });
const commerce = pepay.withAuth({ commerceApiKey: process.env.PEPAY_COMMERCE_API_KEY! });
```

If both keys are configured, the SDK selects the correct header per endpoint and never sends both headers.

## Response

The configured client will automatically attach the correct headers and defaults:

```json theme={null}
{
  "baseUrl": "https://api-beta.pepay.io",
  "auth": ["x-api-key"],
  "timeouts": { "timeoutMs": 30000 },
  "retries": { "maxRetries": 2, "retryableStatusCodes": [429, 500, 503] }
}
```

## Errors

* `401` auth missing/invalid: verify the credential you configured matches the endpoint (merchant vs commerce vs payor).
* `403` forbidden: key may be scoped/suspended, or environment access may not be enabled.
* Browser runtime error when using server keys: use session/ws tokens instead of server API keys.

## Examples

### Retries and timeouts

```ts theme={null}
const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY!,
  timeoutMs: 30_000,
  maxRetries: 2,
  retryableStatusCodes: [429, 500, 503]
});
```

### Browser safety

By default, the SDK rejects server API keys in browser runtimes.

If you truly need to override this (not recommended), you must opt in:

```ts theme={null}
const pepay = new Pepay({
  allowServerKeysInBrowser: true,
  apiKey: 'sk_live_...'
});
```

### WebSockets

WebSocket usage requires a `webSocketFactory` (browser provides `WebSocket`; Node.js typically uses `ws`).

```ts theme={null}
import WebSocket from 'ws';
import { Pepay } from 'pepay';

const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY!,
  baseUrl: process.env.PEPAY_API_URL ?? 'https://api-beta.pepay.io',
  webSocketFactory: WebSocket as any
});
```

Next: [Invoices](/sdk/merchants/invoices)