1# TURN API Reference
2 
3Complete API documentation for Cloudflare TURN service credentials and key management.
4 
5## Authentication
6 
7All endpoints require Cloudflare API token with "Calls Write" permission.
8 
9Base URL: `https://api.cloudflare.com/client/v4`
10 
11## TURN Key Management
12 
13### List TURN Keys
14 
15```
16GET /accounts/{account_id}/calls/turn_keys
17```
18 
19### Get TURN Key Details
20 
21```
22GET /accounts/{account_id}/calls/turn_keys/{key_id}
23```
24 
25### Create TURN Key
26 
27```
28POST /accounts/{account_id}/calls/turn_keys
29Content-Type: application/json
30 
31{
32  "name": "my-turn-key"
33}
34```
35 
36**Response includes**:
37- `uid`: Key identifier
38- `key`: The actual secret key (only returned on creation—save immediately)
39- `name`: Human-readable name
40- `created`: ISO 8601 timestamp
41- `modified`: ISO 8601 timestamp
42 
43### Update TURN Key
44 
45```
46PUT /accounts/{account_id}/calls/turn_keys/{key_id}
47Content-Type: application/json
48 
49{
50  "name": "updated-name"
51}
52```
53 
54### Delete TURN Key
55 
56```
57DELETE /accounts/{account_id}/calls/turn_keys/{key_id}
58```
59 
60## Generate Temporary Credentials
61 
62```
63POST https://rtc.live.cloudflare.com/v1/turn/keys/{key_id}/credentials/generate
64Authorization: Bearer {key_secret}
65Content-Type: application/json
66 
67{
68  "ttl": 86400
69}
70```
71 
72### Credential Constraints
73 
74| Parameter | Min | Max | Default | Notes |
75|-----------|-----|-----|---------|-------|
76| ttl | 1 | 172800 (48hrs) | varies | API rejects values >172800 |
77 
78**CRITICAL**: Maximum TTL is 48 hours (172800 seconds). API will reject requests exceeding this limit.
79 
80### Response Schema
81 
82```json
83{
84  "iceServers": {
85    "urls": [
86      "stun:stun.cloudflare.com:3478",
87      "turn:turn.cloudflare.com:3478?transport=udp",
88      "turn:turn.cloudflare.com:3478?transport=tcp",
89      "turn:turn.cloudflare.com:53?transport=udp",
90      "turn:turn.cloudflare.com:80?transport=tcp",
91      "turns:turn.cloudflare.com:5349?transport=tcp",
92      "turns:turn.cloudflare.com:443?transport=tcp"
93    ],
94    "username": "1738035200:user123",
95    "credential": "base64encodedhmac=="
96  }
97}
98```
99 
100**Port 53 Warning**: Filter port 53 URLs for browser clients—blocked by Chrome/Firefox. See [gotchas.md](./gotchas.md#using-port-53-in-browsers).
101 
102## Revoke Credentials
103 
104```
105POST https://rtc.live.cloudflare.com/v1/turn/keys/{key_id}/credentials/revoke
106Authorization: Bearer {key_secret}
107Content-Type: application/json
108 
109{
110  "username": "1738035200:user123"
111}
112```
113 
114**Response**: 204 No Content
115 
116Billing stops immediately. Active connection drops after short delay (~seconds).
117 
118## TypeScript Types
119 
120```typescript
121interface CloudflareTURNConfig {
122  keyId: string;
123  keySecret: string;
124  ttl?: number; // Max 172800 (48 hours)
125}
126 
127interface TURNCredentialsRequest {
128  ttl?: number; // Max 172800 seconds
129}
130 
131interface TURNCredentialsResponse {
132  iceServers: {
133    urls: string[];
134    username: string;
135    credential: string;
136  };
137}
138 
139interface RTCIceServer {
140  urls: string | string[];
141  username?: string;
142  credential?: string;
143  credentialType?: "password";
144}
145 
146interface TURNKeyResponse {
147  uid: string;
148  key: string; // Only present on creation
149  name: string;
150  created: string;
151  modified: string;
152}
153```
154 
155## Validation Function
156 
157```typescript
158function validateRTCIceServer(obj: unknown): obj is RTCIceServer {
159  if (!obj || typeof obj !== 'object') {
160    return false;
161  }
162 
163  const server = obj as Record<string, unknown>;
164 
165  if (typeof server.urls !== 'string' && !Array.isArray(server.urls)) {
166    return false;
167  }
168 
169  if (server.username && typeof server.username !== 'string') {
170    return false;
171  }
172 
173  if (server.credential && typeof server.credential !== 'string') {
174    return false;
175  }
176 
177  return true;
178}
179```
180 
181## Type-Safe Credential Generation
182 
183```typescript
184async function fetchTURNServers(
185  config: CloudflareTURNConfig
186): Promise<RTCIceServer[]> {
187  // Validate TTL constraint
188  const ttl = config.ttl ?? 3600;
189  if (ttl > 172800) {
190    throw new Error('TTL cannot exceed 172800 seconds (48 hours)');
191  }
192 
193  const response = await fetch(
194    `https://rtc.live.cloudflare.com/v1/turn/keys/${config.keyId}/credentials/generate`,
195    {
196      method: 'POST',
197      headers: {
198        'Authorization': `Bearer ${config.keySecret}`,
199        'Content-Type': 'application/json'
200      },
201      body: JSON.stringify({ ttl })
202    }
203  );
204 
205  if (!response.ok) {
206    throw new Error(`TURN credential generation failed: ${response.status}`);
207  }
208 
209  const data = await response.json();
210  
211  // Filter port 53 for browser clients
212  const filteredUrls = data.iceServers.urls.filter(
213    (url: string) => !url.includes(':53')
214  );
215 
216  const iceServers = [
217    { urls: 'stun:stun.cloudflare.com:3478' },
218    {
219      urls: filteredUrls,
220      username: data.iceServers.username,
221      credential: data.iceServers.credential,
222      credentialType: 'password' as const
223    }
224  ];
225 
226  // Validate before returning
227  if (!iceServers.every(validateRTCIceServer)) {
228    throw new Error('Invalid ICE server configuration received');
229  }
230 
231  return iceServers;
232}
233```
234 
235## See Also
236 
237- [configuration.md](./configuration.md) - Worker setup, environment variables
238- [patterns.md](./patterns.md) - Implementation examples using these APIs
239- [gotchas.md](./gotchas.md) - Security best practices, common mistakes
240