1# Tunnel API
2 
3## Cloudflare API Access
4 
5**Base URL**: `https://api.cloudflare.com/client/v4`
6 
7**Authentication**:
8```bash
9Authorization: Bearer ${CF_API_TOKEN}
10```
11 
12## TypeScript SDK
13 
14Install: `npm install cloudflare`
15 
16```typescript
17import Cloudflare from 'cloudflare';
18 
19const cf = new Cloudflare({
20  apiToken: process.env.CF_API_TOKEN,
21});
22 
23const accountId = process.env.CF_ACCOUNT_ID;
24```
25 
26## Create Tunnel
27 
28### cURL
29```bash
30curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
31  -H "Authorization: Bearer ${CF_API_TOKEN}" \
32  -H "Content-Type: application/json" \
33  --data '{
34    "name": "my-tunnel",
35    "tunnel_secret": "<base64-secret>"
36  }'
37```
38 
39### TypeScript
40```typescript
41const tunnel = await cf.zeroTrust.tunnels.create({
42  account_id: accountId,
43  name: 'my-tunnel',
44  tunnel_secret: Buffer.from(crypto.randomBytes(32)).toString('base64'),
45});
46 
47console.log(`Tunnel ID: ${tunnel.id}`);
48```
49 
50## List Tunnels
51 
52### cURL
53```bash
54curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
55  -H "Authorization: Bearer ${CF_API_TOKEN}"
56```
57 
58### TypeScript
59```typescript
60const tunnels = await cf.zeroTrust.tunnels.list({
61  account_id: accountId,
62});
63 
64for (const tunnel of tunnels.result) {
65  console.log(`${tunnel.name}: ${tunnel.id}`);
66}
67```
68 
69## Get Tunnel Info
70 
71### cURL
72```bash
73curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
74  -H "Authorization: Bearer ${CF_API_TOKEN}"
75```
76 
77### TypeScript
78```typescript
79const tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {
80  account_id: accountId,
81});
82 
83console.log(`Status: ${tunnel.status}`);
84console.log(`Connections: ${tunnel.connections?.length || 0}`);
85```
86 
87## Update Tunnel Config
88 
89### cURL
90```bash
91curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/configurations" \
92  -H "Authorization: Bearer ${CF_API_TOKEN}" \
93  -H "Content-Type: application/json" \
94  --data '{
95    "config": {
96      "ingress": [
97        {"hostname": "app.example.com", "service": "http://localhost:8000"},
98        {"service": "http_status:404"}
99      ]
100    }
101  }'
102```
103 
104### TypeScript
105```typescript
106const config = await cf.zeroTrust.tunnels.configurations.update(
107  tunnelId,
108  {
109    account_id: accountId,
110    config: {
111      ingress: [
112        { hostname: 'app.example.com', service: 'http://localhost:8000' },
113        { service: 'http_status:404' },
114      ],
115    },
116  }
117);
118```
119 
120## Delete Tunnel
121 
122### cURL
123```bash
124curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
125  -H "Authorization: Bearer ${CF_API_TOKEN}"
126```
127 
128### TypeScript
129```typescript
130await cf.zeroTrust.tunnels.delete(tunnelId, {
131  account_id: accountId,
132});
133```
134 
135## Token-Based Tunnels (Config Source: Cloudflare)
136 
137Token-based tunnels store config in Cloudflare dashboard instead of local files.
138 
139### Via Dashboard
1401. **Zero Trust** > **Networks** > **Tunnels**
1412. **Create a tunnel** > **Cloudflared**
1423. Configure routes in dashboard
1434. Copy token
1445. Run on origin:
145```bash
146cloudflared service install <TOKEN>
147```
148 
149### Via Token
150```bash
151# Run with token (no config file needed)
152cloudflared tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
153 
154# Docker
155docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
156```
157 
158### Get Tunnel Token (TypeScript)
159```typescript
160// Get tunnel to retrieve token
161const tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {
162  account_id: accountId,
163});
164 
165// Token available in tunnel.token (only for config source: cloudflare)
166const token = tunnel.token;
167```
168 
169## DNS Routes API
170 
171```bash
172# Create DNS route
173curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections" \
174  -H "Authorization: Bearer ${CF_API_TOKEN}" \
175  --data '{"hostname": "app.example.com"}'
176 
177# Delete route
178curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections/{route_id}" \
179  -H "Authorization: Bearer ${CF_API_TOKEN}"
180```
181 
182## Private Network Routes API
183 
184```bash
185# Add IP route
186curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
187  -H "Authorization: Bearer ${CF_API_TOKEN}" \
188  --data '{"ip_network": "10.0.0.0/8"}'
189 
190# List IP routes
191curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
192  -H "Authorization: Bearer ${CF_API_TOKEN}"
193```
194