# Metered TURN Server Service — llms.txt reference

Metered TURN Servers as a Service provide a globally distributed relay network for WebRTC traffic. The service guarantees connectivity through NATs and firewalls via TURN (Traversal Using Relays around NAT).

- 31+ regions, 100+ edge PoPs, <30 ms latency, 99.999% uptime SLA
- UDP, TCP, TLS, DTLS on ports 80/443. No bandwidth caps per allocation.
- Standards: STUN (RFC 5389), TURN (RFC 5766), ICE
- Private high-speed backbone for cross-continent relay
- REST API for credentials, usage tracking, project isolation
- Dashboard: https://dashboard.metered.ca | Pricing: https://www.metered.ca/pricing

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. Your **app name** (e.g. `yourappname`) is shown on the Dashboard home page. It forms part of the REST API base URL: `https://yourappname.metered.live/api/v1/turn/`.
3. Go to **Dashboard → Developers** to find your **Secret Key**. Use this for all server-side API calls (creating credentials, fetching usage, managing projects). Never expose it in front-end code.
4. **Create a TURN credential**: Go to **Dashboard → TURN Server → Credentials** and click **Create Credential** (classic dashboard: **TURN Server** page → **Add Credential**), or use the Create Credential REST API. Each credential gets:
   - `username` and `password` — used in the ICE server config for WebRTC connections
   - `apiKey` — a credential-scoped key, **safe for front-end use**, used only with the Get Credential API to fetch the ICE server config
5. Click **Get credential → Show ICE Servers Array** on any credential (classic dashboard: the **Show ICE Servers Array** button on the row) to get a ready-to-use ICE config for your WebRTC app. The **ICE** button on a row copies the same array to the clipboard.

**Two dashboards.** Metered has a redesigned dashboard (https://dashboard.metered.ca/v2) and the classic dashboard; both manage the same account, and the API is identical. Users switch with the **Old dashboard** button (new → classic) or by opening /v2 (classic → new). Navigation map (new → classic):
- TURN Server → **Credentials** → *Create Credential* ↔ TURN Server page → *Add Credential*
- Credentials row → **Get credential** → *Show ICE Servers Array* / *Show API Key* / *Delete credential* ↔ row buttons *Show ICE Servers Array* / *Show API Key* / *Remove*
- Credentials row → **ICE** button copies the ICE servers array to the clipboard (no classic equivalent)
- Credentials page → **TURN region** card (new: also a per-credential *Region* in Create Credential) ↔ TURN Server page → *Default TURN Server Region* dropdown
- TURN Server → **Projects** → *New project* / card *Edit* / *Manage* ↔ Projects section on the TURN Server page → *Create Project* / *Edit Project* / *Manage TURN Credentials*
- TURN Server → **Analytics** (new only), **Emergency support** page ↔ Emergency Phone Support panel on the TURN Server page
- **Developers** → *Reveal* / *Reissue it* ↔ Developers → secret key shown / *Regenerate Secret Key*
- **Plans & pricing** page, *Manage subscription* ↔ plan cards at the bottom of the TURN Server page
- Account → **Billing** → *Auto-reload* / *Add Funds* / *Usage History* / *Payment History*; Account → **Team**; Account → **Branding** ↔ Account → *Automatic Billing* / *Add Funds* / *Usage History* / *Payment History* / *Members* / *Custom Branding*

**Three types of API keys:**
- **`secretKey`** — account-scoped, server-side only. Found in Dashboard → Developers.
- **`apiKey`** — credential-scoped, safe for front-end. Returned when creating a credential. Used only for the Get Credential endpoint.
- **`projectApiKey`** — project-scoped, alternative to secretKey for project-level operations. Found in Dashboard → TURN Server → Projects.

---

## Overview & Setup

ICE tries connections in order: host candidates (direct), STUN (public IP discovery), then TURN (full relay fallback). TURN guarantees connectivity through symmetric NAT, carrier-grade NAT, and strict firewalls. The relay forwards encrypted payloads (SRTP/DTLS) without decrypting them.

Use cases: voice/video calls, live streaming, IoT devices, AI/3D/AR/VR, surveillance, DataChannels (chat, gaming, file-share).

### Custom Domain

Point a CNAME at Metered infrastructure (global or region-specific hostname). TURN over TCP and UDP work with CNAME; TURN over TLS does not.

---

## TURN URLs & Ports

### Global Endpoint (recommended)

`global.relay.metered.ca` — automatic geo-routing to nearest edge. STUN: `stun:stun.relay.metered.ca:80`

| Port | Protocol | URI                                              |
|------|----------|--------------------------------------------------|
| 80   | UDP      | turn:global.relay.metered.ca:80                  |
| 80   | TCP      | turn:global.relay.metered.ca:80?transport=tcp    |
| 443  | UDP      | turn:global.relay.metered.ca:443                 |
| 443  | TLS      | turns:global.relay.metered.ca:443?transport=tcp  |

Best practice: include multiple entries (UDP first, then TCP/TLS) for ICE fallback.

### Recommended ICE Servers Array

```json
[
  { "urls": "stun:stun.relay.metered.ca:80" },
  { "urls": "turn:global.relay.metered.ca:80", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turn:global.relay.metered.ca:80?transport=tcp", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turn:global.relay.metered.ca:443", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turns:global.relay.metered.ca:443?transport=tcp", "username": "<USERNAME>", "credential": "<PASSWORD>" }
]
```

### Region-Specific Endpoints

All use ports 80/443. Paid plans only (free plan: `standard.relay.metered.ca` only).

| Region           | Endpoint                       | API region value    |
|------------------|--------------------------------|---------------------|
| Global           | global.relay.metered.ca        | global              |
| North America    | na.relay.metered.ca            | north_america       |
| Europe           | europe.relay.metered.ca        | europe              |
| European Union   | eu.relay.metered.ca            | eu                  |
| Asia             | asia.relay.metered.ca          | asia                |
| Oceania          | oceania.relay.metered.ca       | oceania             |
| US West          | us-west.relay.metered.ca       | us_west             |
| US Central       | us-central.relay.metered.ca    | us_central          |
| US East          | us-east.relay.metered.ca       | us_east             |
| Canada Central   | ca-central.relay.metered.ca    | canada_central      |
| Canada East      | ca-east.relay.metered.ca       | canada_east         |
| Europe West      | eu-west.relay.metered.ca       | europe_west         |
| Europe Central   | eu-central.relay.metered.ca    | europe_central      |
| Asia West        | asia-west.relay.metered.ca     | asia_west           |
| Asia East        | asia-east.relay.metered.ca     | asia_east           |
| Middle East      | middle-east.relay.metered.ca   | middle_east         |
| Canada           | ca.relay.metered.ca            | canada              |
| USA              | us.relay.metered.ca            | usa                 |
| UK               | uk.relay.metered.ca            | uk                  |
| Singapore        | sg.relay.metered.ca            | singapore           |
| India            | in.relay.metered.ca            | india               |
| Seoul            | seoul.relay.metered.ca         | seoul               |
| France           | fr.relay.metered.ca            | france              |
| Germany          | de.relay.metered.ca            | germany             |
| Italy            | it.relay.metered.ca            | italy               |
| Japan            | jp.relay.metered.ca            | japan               |
| Sweden           | se.relay.metered.ca            | sweden              |
| Spain            | es.relay.metered.ca            | spain               |
| Netherlands      | nl.relay.metered.ca            | netherlands         |
| Australia        | au.relay.metered.ca            | australia           |
| Qatar            | qa.relay.metered.ca            | qatar               |
| Standard (free)  | standard.relay.metered.ca      | standard            |

---

## Creating Credentials

**Dashboard**: Log into https://dashboard.metered.ca -> TURN Server -> Credentials -> "Create Credential", then the row's "Get credential" -> "Show ICE Servers Array" to get the config (classic dashboard: TURN Server page -> "Add Credential" -> "Show ICE Servers Array").

**REST API**: POST to Create Credential endpoint (see below). Response includes `username`, `password`, and `apiKey`. Use the `apiKey` to call Get Credential from the front-end. The `apiKey` is credential-scoped and safe for front-end use. The `secretKey` must never be exposed in front-end code.

**Propagation delay**: a newly created credential is not usable immediately. It has to propagate across the global TURN network, which can take **up to 2 minutes**. Before it has propagated, an authenticated Allocate can be rejected and no relay candidate is gathered, even though the credential is valid. Never create a credential at call-setup time; create it ahead of time from the back-end and reuse it. See "Rotating Credentials" below.

---

## Region Pinning

**Dashboard**: Pick the region in the "TURN region" card on the Credentials page, or set a per-credential Region in "Create Credential" (classic dashboard: the "Default TURN Server Region" dropdown); "Show ICE Servers Array" then returns region-scoped endpoints.

**API**: Pass `region` query param to Get Credential API for a specific region. Omit it to use the credential's own region if it was pinned when created on the new dashboard (paid plans), otherwise the dashboard default. Different credentials can target different regions.

**Dynamic updates**: If you use the Get Credential API (with `apiKey`), changing the dashboard region automatically updates what the API returns (for credentials without their own pinned region).

---

## REST API — Authentication

Replace `<appname>` with your app name (Dashboard -> Developers).

**v1 endpoints** (base: `https://<appname>.metered.live/api/v1/turn/`):
Get Credential, Create Credential, Enable Credential, Disable Credential, Delete Credential, Current Usage, Current Usage by Date, Current Usage for User.

**v2 endpoints** (base: `https://<appname>.metered.live/api/v2/turn/`):
Update Credential Label, List Credentials, Current Usage by User, Daily Usage by User, Delete Credential by Label, all Project endpoints.

**v2 payment endpoint** (base: `https://<appname>.metered.live/api/v2/payment/`):
Get Usage Charges — note this uses `/api/v2/payment/`, NOT `/api/v2/turn/`.

Each endpoint below shows its full path including the correct version prefix.

Auth methods (all via query param):
1. `apiKey` — credential-scoped, safe for front-end. Only for Get Credential endpoint.
2. `secretKey` — account-scoped, server-side only. Dashboard -> Developers.
3. `projectApiKey` — project-scoped, alternative to secretKey for project endpoints.

---

## REST API — Credentials

### Get TURN Credential (ICE Servers Array)

Returns the ICE Servers array. Safe for front-end use.

```
GET /api/v1/turn/credentials?apiKey=<CREDENTIAL_API_KEY>
```

Query: `apiKey` (required), `region` (optional, overrides dashboard default).

Response `200 OK` — array of ICE server objects (STUN + TURN entries with urls, username, credential).
Errors: `400` (no API key), `401` (invalid API key).

### Create TURN Credential

```
POST /api/v1/turn/credential?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Body (JSON):
- `expiryInSeconds` (integer, optional) — auto-expire after this many seconds
- `label` (string, optional) — a label for the credential

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.

Errors: `400` (invalid expiry or not subscribed).

**Propagation delay**: a newly created credential is not usable immediately. It has to propagate across the global TURN network, which can take **up to 2 minutes**. Before it has propagated, an authenticated Allocate can be rejected and no relay candidate is gathered, even though the credential is valid. Never create a credential at call-setup time; create it ahead of time from the back-end and reuse it. See "Rotating Credentials" below.

### Enable TURN Credential

Re-enables a previously disabled credential.

```
POST /api/v1/turn/credential/enable?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "message": "Credential enabled successfully" }`
Errors: `400` (missing username, already enabled), `401` (invalid key, not found).

### Disable TURN Credential

```
POST /api/v1/turn/credential/disable?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "message": "Turn credential disabled successfully" }`
Errors: `400` (missing username, already disabled), `401` (not found).

### Delete TURN Credential

```
DELETE /api/v1/turn/credential?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "success": true, "message": "credential removed" }`
Errors: `400` (credential not found).

### Update TURN Credential Label

```
POST /api/v2/turn/credential/update_label?secretKey=<SECRET_KEY>&username=<USERNAME>
```

Body: `{ "label": "<new_label>" }`

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.
Errors: `400` (credential not found).

### List TURN Credentials (v2)

```
GET /api/v2/turn/credentials?secretKey=<SECRET_KEY>
```

Query params:
- `secretKey` (string, required)
- `all` (boolean, optional) — include expired credentials; default false
- `page` (integer, optional) — page number for pagination
- `label` (string, optional) — filter by label

Response `200 OK` — object with `data[]` and `pagination`.

Each credential in `data[]`: `username`, `password`, `apiKey`, `expiryInSeconds`, `label`, `expired` (bool).

`pagination`: `total_records`, `current_page`, `total_pages`, `next_page`, `prev_page`.

Errors: `400` (not subscribed, not available under free plan).

### Delete TURN Credential by Label

Deletes all active (non-expired) credentials matching a label.

```
DELETE /api/v2/turn/credential/by_label?secretKey=<SECRET_KEY>&label=<LABEL>
```

Query params:
- `secretKey` (string, required)
- `label` (string, required) — must be fewer than 100 characters

Response `200 OK`: `{ "deleted": 3 }`

Errors: `400` (missing/invalid secretKey, missing/invalid label, not subscribed).

---

## REST API — Usage

### Get Current Usage

Returns quota, usage, and overage for the current billing cycle.

```
GET /api/v1/turn/current_usage?secretKey=<SECRET_KEY>
```

Response `200 OK` — object with `quotaInGB` (number), `usageInGB` (number), `overageInGB` (number).

Errors: `400` (not subscribed), `500` (internal error).

### Get Current Usage by Date

Returns daily usage breakdown for the current billing cycle.

```
GET /api/v1/turn/current_usage_by_date?secretKey=<SECRET_KEY>
```

Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInGB": <number> }`.

Errors: `400` (not subscribed), `401` (invalid key), `500` (internal error).

### Get Current Usage by User (v2, paginated)

```
GET /api/v2/turn/current_usage_by_user?secretKey=<SECRET_KEY>&page=<PAGE>
```

Query params:
- `secretKey` (string, required)
- `page` (number, optional) — page number for pagination

Response `200 OK` — object with `data[]` (each: `label`, `username`, `usageInGB`) and `has_more` (bool).

Errors: `400` (not subscribed, free plan), `500` (internal error).

### Get Current Usage for a Specific User

```
GET /api/v1/turn/current_usage_for_user?secretKey=<SECRET_KEY>&username=<USERNAME>
```

Response `200 OK`: `{ "usageInGB": 5.2 }`

Errors: `400` (missing secretKey/username, not subscribed), `401` (invalid key, credential not found).

### Get Daily Usage by User (v2, paginated)

Returns daily TURN bandwidth per credential username within a date range.

```
GET /api/v2/turn/usage_daily_by_user?secretKey=<SECRET_KEY>
```

Query params:
- `secretKey` (string, required)
- `startDate` (string, optional) — YYYY-MM-DD, defaults to 6 days before endDate, max 3 months back
- `endDate` (string, optional) — YYYY-MM-DD, defaults to today
- `page` (number, optional) — 1-based, each page returns 7 days

Rate limit: 4 requests per minute per app.

Response `200 OK` — object with `data[]`, `pagination`, and `period`.

Each `data[]` item: `date` (YYYY-MM-DD), `usage[]` (sorted by descending usageInGB). Each usage item: `username`, `label` (or "unlabeled"), `usageInGB`.

`pagination`: `current_page`, `days_per_page` (fixed 7), `has_more`, `total_days`, `total_pages`.
`period`: `start`, `end`, `page_start`, `page_end`.

Errors: `400` (invalid key, not subscribed, free plan, invalid dates, date range >3 months), `500` (internal error).

### Get Usage Charges

Returns charges, payments, and subscription renewals in a date range.

```
GET /api/v2/payment/usage-charges?secretKey=<SECRET_KEY>&startDate=<YYYY-MM-DD>&endDate=<YYYY-MM-DD>
```

Query params:
- `secretKey` (string, required)
- `startDate` (string, required) — YYYY-MM-DD
- `endDate` (string, required) — YYYY-MM-DD

Rate limit: 4 requests per minute per app.

Response `200 OK` — object with `success`, `data[]`, `summary`, and `period`.

Each `data[]` item: `date` (YYYY-MM-DD), `type` (overage|subscription_renewal|recharge), `description`, `total` (USD), `status` (paid|pending). Overage items also have `usage`, `unit` (GB), `unitCharge`. Subscription items have `planName`. Recharge/subscription items have `paymentMethod` (automatic|manual|account_credit).

`summary`: `totalCharges`, `totalOverages`, `totalSubscriptions`, `totalRecharges`, `currency` (USD).
`period`: `startDate`, `endDate`.

Errors: `400` (missing dates, invalid format, end before start, not subscribed, free plan), `401` (invalid key), `500` (internal error).

---

## REST API — Projects

Projects (Business/Enterprise plans only) group TURN credentials with per-project API keys, quotas, notifications, and usage tracking. Each project has a unique ID and API key, optional quota (bytes; 0 = unlimited), exceeded action (`disable`|`notify`|`none`), up to 10 notification emails, and an optional HTTPS webhook URL. Notifications fire at 80% and 100% quota.

### Get Projects

```
GET /api/v2/turn/projects?secretKey=<SECRET_KEY>
```

Response `200 OK` — array of project objects.

Each project: `_id`, `projectName`, `quotaInBytes` (0 = no limit), `webhookUrl` (or null), `notificationEmails` (array), `quotaExceededAction` (disable|notify|none), `created` (ISO 8601).

Errors: `400` (invalid key, not subscribed).

### Create Project

```
POST /api/v2/turn/project?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Body:
- `projectName` (string, required) — must be <100 characters
- `quotaInBytes` (number, optional) — integer >= 1 MiB (1048576); 0 or omitted = no limit
- `webhookUrl` (string, optional) — must start with https://
- `notificationEmails` (array, optional) — max 10 valid email addresses
- `quotaExceededAction` (string, optional) — `disable` (default), `notify`, or `none`

Response `200 OK` — project object with `_id`, `projectName`, `quotaInBytes`, `webhookUrl`, `notificationEmails`, `quotaExceededAction`, `apiKey`, `created` (ISO 8601).

Errors: `400` (invalid key, not subscribed, invalid name/quota/webhook/emails/action).

### Update Project

```
PUT /api/v2/turn/project/:projectId?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Path param: `projectId` (string, required)

Body (all optional):
- `projectName` (string)
- `quotaInBytes` (number) — 0 or >= 1 MiB
- `webhookUrl` (string)
- `notificationEmails` (array)
- `quotaExceededAction` (string)

Response `200 OK`: same shape as Create Project (without `apiKey`).

Errors: `400` (invalid key, not subscribed, project not found, invalid fields).

### Delete Project

Permanently deletes the project and all credentials inside it.

```
DELETE /api/v2/turn/project/:projectId?secretKey=<SECRET_KEY>
```

Response `200 OK`: `{ "success": true }`

Errors: `400` (invalid key, missing/invalid projectId, project not found).

### Regenerate Project API Key

Invalidates the old API key and returns a new one.

```
POST /api/v2/turn/project/:projectId/regenerate_api_key?secretKey=<SECRET_KEY>
```

Response `200 OK`: `{ "apiKey": "pk_aaabbbbccdddd", "success": true }`

Errors: `400` (invalid key, missing/invalid projectId, project not found), `500` (internal error).

### Create Project TURN Credential

```
POST /api/v2/turn/project/:projectId/credential?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body:
- `expiryInSeconds` (number, optional) — positive integer; if omitted, no auto-expire
- `label` (string, optional)

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.

Errors: `400` (invalid projectId, project not found, invalid expiry, not subscribed), `403` (max credential limit reached).

**Propagation delay**: a newly created credential is not usable immediately. It has to propagate across the global TURN network, which can take **up to 2 minutes**. Before it has propagated, an authenticated Allocate can be rejected and no relay candidate is gathered, even though the credential is valid. Never create a credential at call-setup time; create it ahead of time from the back-end and reuse it. See "Rotating Credentials" below.

### Get Credentials for Project

```
GET /api/v2/turn/project/:projectId/credentials?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Query params:
- `page` (number, optional) — default 1, 50 records per page
- `all` (any, optional) — include expired credentials
- `label` (string, optional) — filter by label

Response `200 OK` — object with `data[]` and `pagination`.

Each credential in `data[]`: `_id`, `project`, `username`, `password`, `apiKey`, `manuallyDisabled` (bool), `disabledByProjectRule` (bool).

`pagination`: `total_records`, `current_page`, `total_pages`, `next_page`, `prev_page`.

Errors: `400` (invalid projectId, project not found, not subscribed).

### Delete Project Credential

```
DELETE /api/v2/turn/project/:projectId/credential?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "success": true, "message": "credential removed" }`

Errors: `400` (missing username, credential not found).

### Delete Project Credential by Label

Deletes all active (non-expired) credentials in the project matching a label.

```
DELETE /api/v2/turn/project/:projectId/credential/by_label?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body: `{ "label": "my-labeled-credential" }`

Response `200 OK`: `{ "deleted": 2 }`

Errors: `400` (missing/invalid label, not subscribed).

### Get Current Project Usage

```
GET /api/v2/turn/project/:projectId/current_usage?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — object with `quotaInBytes`, `usageInBytes`, `overageInBytes`.

Errors: `400` (not subscribed, project not found), `500` (internal error).

### Get Current Project Usage by Date

```
GET /api/v2/turn/project/:projectId/current_usage_by_date?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInBytes": <number> }`.

Errors: `400` (project not found).

### Get Current Project Usage by User

```
GET /api/v2/turn/project/:projectId/current_usage_by_user?secretKey=<SECRET_KEY>&page=<PAGE>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Query params: `page` (number, optional) — default 1, 25 records per page.

Response `200 OK` — object with `data[]` (each: `label`, `username`, `usageInBytes`) and `has_more` (bool). Note: `usageInBytes` may be a string; parse as needed.

Errors: `400` (not subscribed, project not found).

### Get Project Usage for a Specific User

```
GET /api/v2/turn/project/:projectId/current_usage_for_user?secretKey=<SECRET_KEY>&username=<USERNAME>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — object with `label` and `usageInBytes` (may be string).

Errors: `400` (missing username), `401` (credential not found).

---

## Expiring Credentials

Expiring credentials auto-disable after a set duration, preventing leaked credentials from being reused. Recommended for production.

**Flow**: Back-end calls Create Credential with `expiryInSeconds` (e.g., 14400 for 4 hours) -> gets `username`, `password`, `apiKey` -> returns `apiKey` to front-end -> front-end calls `GET /api/v1/turn/credentials?apiKey=<apiKey>` to get ICE Servers array -> credential auto-expires.

Always call the Create Credential API from the back-end (never front-end). Project-scoped credentials also support `expiryInSeconds`.

**Two constraints**:
- A new credential takes **up to 2 minutes** to propagate across the global TURN network before it is usable.
- The expiry is a **hard cutoff**: when `expiryInSeconds` elapses the credential stops working immediately, including for calls already in progress.

Together these rule out "short-lived credential created just before the call". Use scheduled rotation instead (below).

---

## Rotating Credentials

Docs: https://www.metered.ca/docs/turnserver-guides/rotating-turn-credentials/

Recommended production scheme: **48 hour lifetime, rotated every 24 hours**, so credentials overlap.

- Create each credential with `expiryInSeconds: 172800` (48 h) and a `label`.
- Issue a fresh one every 24 h from a scheduled back-end job (cron / scheduled function / interval).
- Do **not** delete the outgoing credential at rotation time; let it expire, or delete it after the overlap window.

Cycle: Day 0 create A (valid to Day 2) -> Day 1 create B (valid to Day 3), hand B to clients, A still valid -> Day 2 A expires, everyone has had 24 h to pick up B -> Day 3 create C.

Why rotate at half the lifetime:
- Any credential a client holds always has >= 24 h validity left, so it can never expire mid-call.
- Each credential is created a full day before it is needed, so the up-to-2-minute propagation delay is never on the critical path.
- A client that missed a refresh (offline, backgrounded) still holds a valid credential.

Serving it: back-end returns the credential-scoped `apiKey` to the client; the client calls `GET /api/v1/turn/credentials?apiKey=<apiKey>` for the full ICE servers array. The `secretKey` never leaves the back-end. One credential can serve many calls — no need for per-call or per-user credentials.

Cleanup: list with `GET /api/v2/turn/credentials?secretKey=<KEY>&label=<LABEL>`; delete with `DELETE /api/v2/turn/credential/by_label` (removes **all** active credentials with that label, including the current one) or `DELETE /api/v1/turn/credential` with a single `username`.

Leaked credential: disable or delete that `username` immediately, create a replacement, and expect a short window (up to 2 minutes) while the replacement propagates.

If you change the numbers, keep both rules: rotate at no more than half the lifetime, and keep the lifetime well above your longest expected call.

Anti-patterns: creating a credential when the user clicks "join" (not propagated yet); one credential per call or per user (no benefit, same delay each time); an expiry sized to one call (dies mid-call for long calls); deleting the old credential at rotation (breaks unrefreshed clients); calling Create Credential from the front-end (exposes the Secret Key).

### Rotating a pool of credentials

The same 48 h / 24 h cycle runs across one credential or a pool of them; how many is a separate decision, driven by what you need to keep apart. Use a pool, each slot on its own cycle, when you want to:
- **Contain a leak** — disable one slot instead of the single credential everyone holds, so only that slot's clients are affected.
- **Attribute usage** — each credential is metered separately via `GET /api/v1/turn/current_usage_for_user?username=<slot username>`, so a slot per environment / region / major customer yields a usage breakdown.
- **Spread out creation** — rotate one slot per interval instead of replacing everything at once.

**Sizing**: one slot per thing you actually want to separate; the count falls out of that. Suits a handful of stable cohorts (staging vs production, a few named customers). Do **not** give every tenant a slot when tenants are numerous or churn — that is what Projects is for.

**Plan cap**: every plan limits how many credentials can be active at once; past the cap, creation is rejected (the project endpoint documents this as `403 Maximum credential limit reached`). Treat it as a signal to delete unneeded credentials or shrink the pool, not to retry in a loop. Do not state a specific cap — it varies by plan.

**Business / Enterprise**: prefer TURN Projects (own API key, quota, usage tracking, webhooks, no slot table). Use a pool when Projects is unavailable on the plan, or to segment inside a project.

**Mechanics**: each slot runs the normal cycle independently, offset in phase; rotate one slot every (rotation period / pool size). Label each slot stably (e.g. `pool-0`) to find its current credential. Assign clients by a stable hash of an id you already have, so a client keeps its slot and per-slot usage stays meaningful. During a slot's overlap window it has two live credentials — sum both for that slot's usage.

**Retiring a slot**: do NOT use `DELETE /api/v2/turn/credential/by_label` on a slot label during overlap — it removes the replacement too, cutting off clients that already moved across. Delete or disable one `username` at a time; delete-by-label is correct only when the whole slot should go.

**Leak response with a pool**: disable the affected slot's `username`, rotate that slot immediately, have its clients re-fetch. Other slots are untouched.

---

## Project Webhooks

When a project has a webhook URL, HTTP POST requests fire at two thresholds:
- `project_quota_80_percent` — usage crosses 80% of quota
- `project_quota_exceeded` — usage crosses 100% of quota

**Payload**: JSON with `event`, `project` (ID), `projectName`, `app` (ID), `quota` (bytes), `usage` (bytes).

**Security**: `X-Metered-Signature-256` header contains `sha256=<hex_hmac>`. Verify by computing HMAC-SHA256 of the raw body with Project API Key as secret.

**Requirements**: HTTPS endpoint, POST, return 2xx. System retries on failure.

**Notes**: Quota 0 = no events. One notification per threshold per quota setting. Modifying quota resets thresholds.