Skip to main content
This guide walks you through manually migrating ngrok Endpoint configurations to Cloud Endpoints with appropriate Traffic policies.

​
Prerequisites

​
Important notes

  • Dry Run First: Test Traffic Policies without deleting anything.
  • Backup Everything: Save JSON exports of your current configurations.
  • Check your protocols: Not everything is supported on TCP / TLS.

​
1. Set up environment

Make sure you have:
  • NGROK_API_TOKEN (your personal or organization token).
  • API Base URL: https://api.ngrok.com.
Example Header for all API requests: 
Authorization: Bearer YOUR_NGROK_API_TOKEN
Ngrok-Version: 2
Content-Type: application/json

​
2. Retrieve existing endpoint configurations

Get a list of all current endpoint configurations: 
curl -H "Authorization: Bearer YOUR_NGROK_API_TOKEN" \
     -H "Ngrok-Version: 2" \
     https://api.ngrok.com/endpoint_configurations
Save the response. Each object represents an existing endpoint you may need to migrate.

​
3. Retrieve reserved domains and addresses

You must associate reserved domains and addresses with endpoint configurations manually. Reserved domains (HTTP / HTTPS): 
curl -H "Authorization: Bearer YOUR_NGROK_API_TOKEN" \
     -H "Ngrok-Version: 2" \
     https://api.ngrok.com/reserved_domains
Reserved addresses (TCP): 
curl -H "Authorization: Bearer YOUR_NGROK_API_TOKEN" \
     -H "Ngrok-Version: 2" \
     https://api.ngrok.com/reserved_addrs
Match reserved domains/addresses to endpoint configurations:
  • For domains, check if http_endpoint_configuration or https_endpoint_configuration is populated.
  • For addresses, check if endpoint_configuration is populated.

​
4. Build a Traffic Policy for each endpoint

For each endpoint configuration:
  1. Analyze features enabled on the endpoint:
    • OAuth? OIDC? Webhook verification? TLS termination?
    • Request/response header modifications?
    • IP restrictions?
    • Circuit breaker or compression?
  2. Translate module configuration to Traffic Policy YAML. 📚 Guide: How to Migrate Each Endpoint Configuration Module to Traffic Policy Actions
To help start you off, here is a basic Traffic Policy skeleton in YAML: 
on_http_request: []
on_http_response: []
on_tcp_connect: []

​
5. Create a new Cloud Endpoint

Once your Traffic Policy YAML is ready: Create a new Cloud Endpoint: 
curl -X POST \
     -H "Authorization: Bearer YOUR_NGROK_API_TOKEN" \
     -H "Ngrok-Version: 2" \
     -H "Content-Type: application/json" \
     -d '{
           "description": "Migrated from endpoint configuration ID",
           "type": "cloud",
           "url": "<address or domain>",
           "traffic_policy": "--- YOUR POLICY YAML STRINGIFIED HERE ---"
         }' \
     https://api.ngrok.com/endpoints
Make sure:
  • url matches the domain or address associated with the old configuration.
  • traffic_policy is stringified and properly escaped, using third-party tools can help with this.

​
6. Delete the old endpoint configuration

Once the new endpoint is verified to work: 
curl -X DELETE \
     -H "Authorization: Bearer YOUR_NGROK_API_TOKEN" \
     -H "Ngrok-Version: 2" \
     https://api.ngrok.com/endpoint_configurations/YOUR_ENDPOINT_CONFIG_ID

​
7. Repeat for all endpoint configurations

  • Repeat Steps 2-6 for every domain and address you have attached to the endpoint config.
  • Be careful if endpoints have multiple domains/addresses attached.
After completing the process, your endpoints will be managed under Cloud Endpoints with fine-grained Traffic Policies, allowing better modular management and control.

​
What’s next?

Here are some guides to help get you started with Traffic Policy: