Skip to content
Cloudflare Docs

Create a tunnel (API)

Follow this guide to set up a Cloudflare Tunnel using the API.

Create an API token

Create an API token with the following permissions:

TypeItemPermission
AccountCloudflare TunnelEdit
ZoneDNSEdit

2. Create a tunnel

Make a POST request to the Cloudflare Tunnel endpoint:

Required API token permissions

 At least one of the following token permissions is required:
  • Cloudflare One Connectors Write
  • Cloudflare One Connector: cloudflared Write
  • Cloudflare Tunnel Write
Create a Cloudflare Tunnel
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "api-tunnel",
    "config_src": "cloudflare"
  }'
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
    "account_tag": "699d98642c564d2e855e9661899b7252",
    "created_at": "2025-02-18T22:41:43.534395Z",
    "deleted_at": null,
    "name": "example-tunnel",
    "connections": [],
    "conns_active_at": null,
    "conns_inactive_at": "2025-02-18T22:41:43.534395Z",
    "tun_type": "cfd_tunnel",
    "metadata": {},
    "status": "inactive",
    "remote_config": true,
    "credentials_file": {
      "AccountTag": "699d98642c564d2e855e9661899b7252",
      "TunnelID": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
      "TunnelName": "api-tunnel",
      "TunnelSecret": "bTSquyUGwLQjYJn8cI8S1h6M6wUc2ajIeT7JotlxI7TqNqdKFhuQwX3O8irSnb=="
    },
    "token": "eyJhIjoiNWFiNGU5Z..."
  }
}

Copy the id and token values shown in the output. You will need these values to configure and run the tunnel.

The next steps depend on whether you want to connect an application or connect a network.

3a. Connect an application

Before you connect an application through your tunnel, you must:

Follow these steps to connect an application through your tunnel. If you are looking to connect a network, skip to the Connect a network section.

  1. Make a PUT request to route your local service URL to a public hostname. For example,

    Required API token permissions

     At least one of the following token permissions is required:
    • Cloudflare One Connectors Write
    • Cloudflare One Connector: cloudflared Write
    • Cloudflare Tunnel Write
    Put configuration
    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/configurations" \
      --request PUT \
      --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
      --json '{
        "config": {
            "ingress": [
                {
                    "hostname": "app.example.com",
                    "service": "http://localhost:8001",
                    "originRequest": {}
                },
                {
                    "service": "http_status:404"
                }
            ]
        }
      }'

    Your ingress rules must include a catch-all rule at the end. In this example, cloudflared will respond with a 404 status code when the request does not match any of the previous hostnames.

  2. Create a DNS record for your application:

    Required API token permissions

     At least one of the following token permissions is required:
    • DNS Write
    Create DNS Record
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
      --request POST \
      --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
      --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
      --json '{
        "type": "CNAME",
        "proxied": true,
        "name": "app.example.com",
        "content": "c1744f8b-faa1-48a4-9e5c-02ac921467fa.cfargotunnel.com"
      }'

    This DNS record allows Cloudflare to proxy app.example.com traffic to your Cloudflare Tunnel (<tunnel-id>.cfargotunnel.com).

This application will be publicly available on the Internet once you run the tunnel. To allow or block specific users, create an Access application.

3b. Connect a network

To connect a private network through your tunnel, add a tunnel route:

Required API token permissions

 At least one of the following token permissions is required:
  • Cloudflare One Networks Write
  • Cloudflare Tunnel Write
Create a tunnel route
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "network": "172.16.0.0/16",
    "tunnel_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
    "comment": "Example private network route"
  }'

To configure Zero Trust policies and connect as a user, refer to Connect private networks.

4. Install and run the tunnel

Install cloudflared on your server and run the tunnel using the token value obtained in 2. Create a tunnel. You can also get the tunnel token using the Cloudflare Tunnel token endpoint.

  1. Download and install ↗ cloudflared.

  2. Run the following command:

    Terminal window
    sudo cloudflared service install <TUNNEL_TOKEN>

5. Verify tunnel status

To check if the tunnel is serving traffic:

Required API token permissions

 At least one of the following token permissions is required:
  • Cloudflare One Connectors Write
  • Cloudflare One Connectors Read
  • Cloudflare One Connector: cloudflared Write
  • Cloudflare One Connector: cloudflared Read
  • Cloudflare Tunnel Write
  • Cloudflare Tunnel Read
Get a Cloudflare Tunnel
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/c1744f8b-faa1-48a4-9e5c-02ac921467fa" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
    "account_tag": "699d98642c564d2e855e9661899b7252",
    "created_at": "2025-02-18T22:41:43.534395Z",
    "deleted_at": null,
    "name": "example-tunnel",
    "connections": [
      {
        "colo_name": "bos01",
        "uuid": "2xz99mfm-a59e-4924-gyh9-z9vafaw6k0i2",
        "id": "2xz99mfm-a59e-4924-gyh9-z9vafaw6k0i2",
        "is_pending_reconnect": false,
        "origin_ip": "10.1.0.137",
        "opened_at": "2025-02-19T19:11:12.101642Z",
        "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a",
        "client_version": "2025.2.0"
      },
      {
        "colo_name": "phl01",
        "uuid": "axe2socu-2fb5-3akx-b860-898zyes3cs9q",
        "id": "axe2socu-2fb5-3akx-b860-898zyes3cs9q",
        "is_pending_reconnect": false,
        "origin_ip": "10.1.0.137",
        "opened_at": "2025-02-19T19:11:12.006297Z",
        "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a",
        "client_version": "2025.2.0"
      },
      {
        "colo_name": "phl01",
        "uuid": "9b5y0wm9-ca7f-ibq6-8ff4-sm53xekfyym1",
        "id": "9b5y0wm9-ca7f-ibq6-8ff4-sm53xekfyym1",
        "is_pending_reconnect": false,
        "origin_ip": "10.1.0.137",
        "opened_at": "2025-02-19T19:11:12.004721Z",
        "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a",
        "client_version": "2025.2.0"
      },
      {
        "colo_name": "bos01",
        "uuid": "g6cdeiz1-80f5-3akx-b18b-3y0ggktoxwkd",
        "id": "g6cdeiz1-80f5-3akx-b18b-3y0ggktoxwkd",
        "is_pending_reconnect": false,
        "origin_ip": "10.1.0.137",
        "opened_at": "2025-02-19T19:11:12.110765Z",
        "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a",
        "client_version": "2025.2.0"
      }
    ],
    "conns_active_at": "2025-02-19T19:11:12.004721Z",
    "conns_inactive_at": null,
    "tun_type": "cfd_tunnel",
    "metadata": {},
    "status": "healthy",
    "remote_config": true
  }
}

A healthy tunnel will have four connections to Cloudflare's network.