# 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** and click **"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 **"Show ICE Servers Array"** on any credential in the Dashboard to get a ready-to-use ICE config for your WebRTC app. **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": "", "credential": "" }, { "urls": "turn:global.relay.metered.ca:80?transport=tcp", "username": "", "credential": "" }, { "urls": "turn:global.relay.metered.ca:443", "username": "", "credential": "" }, { "urls": "turns:global.relay.metered.ca:443?transport=tcp", "username": "", "credential": "" } ] ``` ### 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 page -> "Add Credential" -> "Show ICE Servers Array" to get the config. **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. --- ## Region Pinning **Dashboard**: Select region from dropdown; "Show ICE Servers Array" returns region-scoped endpoints. **API**: Pass `region` query param to Get Credential API for a specific region. Omit it to use 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. --- ## REST API — Authentication Replace `` with your app name (Dashboard -> Developers). **v1 endpoints** (base: `https://.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://.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://.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= ``` 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= 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). ### Enable TURN Credential Re-enables a previously disabled credential. ``` POST /api/v1/turn/credential/enable?secretKey= ``` Body: `{ "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= ``` Body: `{ "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= ``` Body: `{ "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=&username= ``` Body: `{ "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= ``` 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=&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= ``` 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= ``` Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInGB": }`. 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=&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=&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= ``` 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=&startDate=&endDate= ``` 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= ``` 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= 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= 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= ``` 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= ``` 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= (or ?projectApiKey=) 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). ### Get Credentials for Project ``` GET /api/v2/turn/project/:projectId/credentials?secretKey= (or ?projectApiKey=) ``` 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= (or ?projectApiKey=) Content-Type: application/json ``` Body: `{ "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= (or ?projectApiKey=) 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= (or ?projectApiKey=) ``` 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= (or ?projectApiKey=) ``` Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInBytes": }`. Errors: `400` (project not found). ### Get Current Project Usage by User ``` GET /api/v2/turn/project/:projectId/current_usage_by_user?secretKey=&page= (or ?projectApiKey=) ``` 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=&username= (or ?projectApiKey=) ``` 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=` 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`. --- ## 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=`. 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.