ngrok

https://ngrok.com/docs
Admin
ngrok is a tool that creates secure tunnels from a public endpoint to a locally running web service,...
Tokens:1,736,096
Snippets:13,775
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### ngrok service install, start, and stop example

Source: https://ngrok.com/docs/gateway/agent/cli

Installs the ngrok service with a specified config file, then starts and stops the service. When installed, the service runs as if invoked with 'ngrok start --all'.

```bash
ngrok service install --config=C:\ngrok.yml
ngrok service start
ngrok service stop

```

--------------------------------

### Install and start ngrok as a service

Source: https://ngrok.com/docs/gateway/device-gateway/quickstart

Install ngrok as a background service for production deployments, then start it. The service starts automatically and recovers from crashes.

```bash
ngrok service install --config /path/to/ngrok.yml
ngrok service start

```

--------------------------------

### Install and start the Slack sample app

Source: https://ngrok.com/docs/integrations/webhooks/slack-webhooks

Clone the sample Node.js app and install dependencies, then start the Slack sample. The app runs on port 3000 by default.

```bash
git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
cd ngrok-webhook-nodejs-sample
npm install

```

```bash
npm run startSlack

```

--------------------------------

### ngrok start examples

Source: https://ngrok.com/docs/gateway/agent/cli

Starts tunnels by name from the configuration file. Use --all to start all defined tunnels.

```bash
ngrok start dev        # start tunnel named 'dev' in the configuration file
ngrok start web blog   # start tunnels named 'web' and 'blog'
ngrok start --all      # start all tunnels defined in the config file

```

--------------------------------

### Install and start ngrokd on Mac, Linux, Windows, or Docker

Source: https://ngrok.com/docs/gateway/site-to-site-connectivity/non-k8s-environment

Install and start ngrokd on your local environment, then set your ngrok API key. The Mac and Linux commands are identical; Windows requires running as Administrator and uses a different installer. Docker requires the NET_ADMIN capability and mounts a volume for persistent configuration.

```bash
curl -fsSL https://raw.githubusercontent.com/ngrok/ngrokd/main/install.sh | sudo bash
sudo ngrokd install
sudo ngrokd start
ngrokctl set-api-key YOUR_NGROK_API_KEY

```

```bash
curl -fsSL https://raw.githubusercontent.com/ngrok/ngrokd/main/install.sh | sudo bash
sudo ngrokd install
sudo ngrokd start
ngrokctl set-api-key YOUR_NGROK_API_KEY

```

```powershell
# Run as Administrator
iwr -useb https://raw.githubusercontent.com/ngrok/ngrokd/main/install.ps1 | iex
Start-Process ngrokd -ArgumentList '--config=C:\ProgramData\ngrokd\config.yml' -WindowStyle Hidden
ngrokctl set-api-key YOUR_NGROK_API_KEY

```

```bash
docker pull ngrok/ngrokd:latest
docker run -d \
  --name ngrokd \
  --cap-add=NET_ADMIN \
  -e NGROK_API_KEY=<YOUR_NGROK_API_KEY> \
  -v ngrokd-data:/etc/ngrokd \
  ngrok/ngrokd:latest

```

--------------------------------

### Start internal Agent endpoint for query parameters example

Source: https://ngrok.com/docs/gateway/traffic-policy/actions/http-request

Starts an internal Agent endpoint that exposes https://httpbin.org as https://httpbin.internal. Required to simulate the query parameters example.

```bash
ngrok http https://httpbin.org --host-header rewrite --url https://httpbin.internal

```

--------------------------------

### Install and start ngrok as a background service

Source: https://ngrok.com/docs/gateway/agent/service

Install ngrok as a background service using a configuration file that includes the authtoken and endpoints, then start the service. The install command validates the configuration file and records the executable and config file locations, so do not move or delete them afterward. If you see exit code 5 or 'Input/output error', ngrok cannot find or read the config file.

```bash
ngrok service install --config C:\ngrok\ngrok.yml
```

```bash
ngrok service start
```

--------------------------------

### Install and start ngrokd on macOS/Linux

Source: https://ngrok.com/docs/gateway/device-gateway/private-connectivity

Install ngrokd on macOS or Linux, start it, and set your API key. Requires sudo privileges and an ngrok API key.

```bash
curl -fsSL https://raw.githubusercontent.com/ngrok/ngrokd/main/install.sh | sudo bash
sudo ngrokd install
sudo ngrokd start
ngrokctl set-api-key YOUR_NGROK_API_KEY

```

--------------------------------

### Install and start ngrokd on Windows

Source: https://ngrok.com/docs/gateway/device-gateway/private-connectivity

Install ngrokd on Windows as Administrator, start it hidden with a specified config file, and set your API key.

```powershell
# Run as Administrator
iwr -useb https://raw.githubusercontent.com/ngrok/ngrokd/main/install.ps1 | iex
Start-Process ngrokd -ArgumentList '--config=C:\ProgramData\ngrokd\config.yml' -WindowStyle Hidden
ngrokctl set-api-key YOUR_NGROK_API_KEY

```

--------------------------------

### Install and run the sample Node.js app

Source: https://ngrok.com/docs/integrations/webhooks/alchemy-webhooks

Clone the sample Node.js app from GitHub, install its dependencies, and start it. The app runs on port 3000 by default and logs request headers and body in the terminal.

```bash
git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
cd ngrok-webhook-nodejs-sample
npm install

```

```bash
npm start

```

--------------------------------

### Start a credit purchase with cURL, Python, JavaScript, PHP, Go, Java, and Ruby

Source: https://ngrok.com/docs/ai-gateway/api-reference/credits/purchase-create

These examples show how to start a credit purchase by sending a POST request to https://api.ngrok.ai/credits/purchases with an amount of 25000. Each example uses the same endpoint and payload, differing only in the client library or language. The Authorization header must contain a valid bearer token.

```bash
curl --request POST \
  --url https://api.ngrok.ai/credits/purchases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25000
}
'
```

```python
import requests

url = "https://api.ngrok.ai/credits/purchases"

payload = { "amount": 25000 }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

```javascript
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({amount: 25000})
};

fetch('https://api.ngrok.ai/credits/purchases', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ngrok.ai/credits/purchases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 25000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ngrok.ai/credits/purchases"

	payload := strings.NewReader("{\n  \"amount\": 25000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.post("https://api.ngrok.ai/credits/purchases")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 25000\n}")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.ngrok.ai/credits/purchases")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 25000\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### ngrok Docker command examples

Source: https://ngrok.com/docs/using-ngrok-with/docker

A collection of example commands showing various ngrok Docker usages: HTTP, HTTPS, TCP, TLS, and starting tunnels from a config file.

```bash
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80                            # secure public URL for port 80 web server
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http --url baz.ngrok.dev 8080   # port 8080 available at baz.ngrok.dev
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http foo.dev:80                    # tunnel to host:port instead of localhost
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http https://localhost:5001        # expose a local https server running on port 5001
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tcp 22                             # tunnel arbitrary TCP traffic to port 22
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tls --url foo.com 443           # TLS traffic for foo.com to port 443
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest start foo bar baz                  # start tunnels from the configuration file

```

--------------------------------

### Clone and install the sample Node.js app

Source: https://ngrok.com/docs/integrations/webhooks/airship-webhooks

Commands to clone the ngrok webhook Node.js sample repository and install its dependencies. Run these in a terminal before starting the app.

```bash
git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
cd ngrok-webhook-nodejs-sample
npm install

```

--------------------------------

### Install Go SDK and Initialize Module

Source: https://ngrok.com/docs/getting-started/go

Commands to create a new Go module and install the ngrok SDK v2.

```bash
mkdir ngrok-go-demo
cd ngrok-go-demo
go mod init ngrok-go-demo
go get golang.ngrok.com/ngrok/v2
```

--------------------------------

### Example request for response headers

Source: https://ngrok.com/docs/gateway/traffic-policy/actions/add-headers

Example request and response showing the added headers on a GET request to /status/200. The response includes x-custom-header and x-string-interpolation-example with the interpolated start time.

```bash
$ curl -i https://httpbin.ngrok.app/status/200

```

```http
HTTP/2 200 OK
x-custom-header: my-custom-value
x-string-interpolation-example: started at 2024-07-13T00:10:16Z

```

--------------------------------

### Start tunnel - Example request body

Source: https://ngrok.com/docs/gateway/agent/api

Example JSON request body for POST /api/tunnels to start a new tunnel. Parameters match those used in the configuration file; this example starts a TCP tunnel named 'ssh' forwarding to port 22.

```json
{
    "addr": "22",
    "proto": "tcp",
    "name": "ssh"
}
```

--------------------------------

### Create project directory and .env file

Source: https://ngrok.com/docs/getting-started/javascript

Creates a new directory for the demo, navigates into it, and creates an empty .env file.

```bash
mkdir ngrok-javascript-demo && cd ngrok-javascript-demo
touch .env

```

--------------------------------

### Go SDK: install, forward, and set authtoken

Source: https://ngrok.com/docs/agent-sdks

Install the Go SDK, add a minimal app that forwards to localhost:8085, and set the authtoken environment variable.

```bash
go get golang.ngrok.com/ngrok/v2

```

```go
import "golang.ngrok.com/ngrok/v2"

func connectNgrok() {
    fwd, err := ngrok.Forward(context.Background(),
        ngrok.WithUpstream("http://localhost:8085"),
    )
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Available at:", fwd.URL())
    select {}
}

```

```bash
export NGROK_AUTHTOKEN=<token>

```

--------------------------------

### ngrok start usage

Source: https://ngrok.com/docs/gateway/agent/cli

Shows the general syntax for the ngrok start command, which starts endpoints by name from the configuration file.

```bash
ngrok start [flags]

```

--------------------------------

### Start tunnel - Example response

Source: https://ngrok.com/docs/gateway/agent/api

Example JSON response from POST /api/tunnels with a 201 Created status. Shows the started tunnel's details including public URL, protocol, config, and metrics.

```json
{
    "name": "",
    "uri": "/api/tunnels/",
    "public_url": "tcp://0.tcp.ngrok.io:53476",
    "proto": "tcp",
    "config": {
        "addr": "localhost:22",
        "inspect": false
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}
```

--------------------------------

### Start the Okta sample app

Source: https://ngrok.com/docs/integrations/webhooks/okta-webhooks

Command to start the sample app that runs on port 3000 by default.

```bash
npm run startOkta

```

--------------------------------

### Example output showing a finalizer on a CloudEndpoint

Source: https://ngrok.com/docs/gateway/k8s/guides/finalizers

Example output from the kubectl get command showing a CloudEndpoint resource with a finalizer.

```yaml
apiVersion: ngrok.k8s.ngrok.com/v1
kind: CloudEndpoint
metadata:
  name: my-endpoint
  finalizers:
  - ngrok.k8s.ngrok.com/finalizer

```

--------------------------------

### GET /endpoints

Source: https://ngrok.com/docs/api-reference/endpoints/list

Documentation for the GET /endpoints endpoint, including parameters, request example, response schema, and error responses.

```APIDOC
## [GET] /endpoints

### Description
Lists all active endpoints on the ngrok account. This endpoint returns a paginated list of endpoints with their details.

### Method
GET

### Endpoint
https://api.ngrok.com/endpoints

### Parameters
#### Query Parameters
- **before_id** (string) - Optional - Expects a resource ID as its input. Returns earlier entries in the result set, sorted by ID.
- **limit** (string) - Optional - Constrains the number of results in the dataset. See the API Overview for details.
- **filter** (string) - Optional - A CEL expression to filter the list results. Supports logical and comparison operators to match on fields such as `id`, `metadata`, `created_at`, and more. See ngrok API Filtering for syntax and field details: https://ngrok.com/docs/api/api-filtering. Filterable fields: id, url, type, pooling_enabled, region, scheme, description, metadata, name, created_at, principal.id, bindings

### Request Example
```
GET /endpoints HTTP/1.1
Host: api.ngrok.com
ngrok-version: 2
Authorization: Bearer <token>
```

### Response
#### Success Response (200)
- **endpoints** (object[]) - The list of all active endpoints on this account
- **uri** (string) - URI of the endpoints list API resource
- **next_page_uri** (string) - URI of the next page, or null if there is no next page

#### Response Example
```
{
  "endpoints": [
    {
      "id": "<string>",
      "region": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "public_url": "<string>",
      "proto": "<string>",
      "scheme": "<string>",
      "hostport": "<string>",
      "host": "<string>",
      "port": 123,
      "type": "<string>",
      "metadata": "<string>",
      "description": "<string>",
      "domain": {
        "id": "<string>",
        "uri": "<string>"
      },
      "tcp_addr": {
        "id": "<string>",
        "uri": "<string>"
      },
      "tunnel": {
        "id": "<string>",
        "uri": "<string>"
      },
      "edge": {
        "id": "<string>",
        "uri": "<string>"
      },
      "upstream_url": "<string>",
      "upstream_protocol": "<string>",
      "url": "<string>",
      "principal": {
        "id": "<string>",
        "uri": "<string>"
      },
      "traffic_policy": "<string>",
      "bindings": [
        "<string>"
      ],
      "tunnel_session": {
        "id": "<string>",
        "uri": "<string>"
      },
      "uri": "<string>",
      "name": "<string>",
      "pooling_enabled": true
    }
  ],
  "uri": "<string>",
  "next_page_uri": "<string>"
}
```

#### Error Responses
- **4XX** - Client error. Response body example:
```
{
  "status_code": 123,
  "msg": "<string>",
  "error_code": "<string>",
  "details": {}
}
```
- **5XX** - Server error. Response body example:
```
{
  "status_code": 123,
  "msg": "<string>",
  "error_code": "<string>",
  "details": {}
}
```

### Authorizations
- **Authorization** (string, header, required) - Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

### Headers
- **ngrok-version** (integer, default:2, required) - API version header.
```

--------------------------------

### ngrok CLI example commands

Source: https://ngrok.com/docs/gateway/agent/cli

A collection of example ngrok commands demonstrating HTTP and TCP tunnels, custom URLs, traffic policies, network forwarding, load balancing, private services, Kubernetes binding, and starting multiple endpoints from the config file.

```bash
# forward http traffic from assigned public URL to local port 80
ngrok http 80

# choose a URL instead of random assignment
ngrok http 8080 --url https://baz.ngrok.dev

# manipulate traffic to your endpoint with a traffic policy file
ngrok http 8080 --url https://baz.ngrok.dev --traffic-policy-file tp.yml

# forward to another address on the network instead of a local port
ngrok http foo.local:3000

# forward to a local https server
ngrok http https://localhost:8443

# forward TCP traffic (e.g. ssh) with an assigned public address
ngrok tcp 22

# load balance (in two terminals)
ngrok http 80 --url https://api.example.com --pooling-enabled
ngrok http 80 --url https://api.example.com --pooling-enabled

# privately connect a service to the ngrok cloud.
# then forward traffic from other endpoints in your account to it
ngrok http 80 --url https://svc.internal
ngrok tcp 5432 --url tcp://postgres.internal:5432

# make your endpoint url addressable only from k8s clusters
# where you've installed the ngrok k8s operator
ngrok http 80 --url https://example.namespace --binding kubernetes

# start multiple endpoints defined in the config file
ngrok start foo bar baz

```

--------------------------------

### Start the sample Node.js app

Source: https://ngrok.com/docs/integrations/webhooks/airship-webhooks

Command to start the sample app. It runs on port 3000 by default and logs request headers and body in the terminal.

```bash
npm start

```

--------------------------------

### List TLS certificates with GET /tls_certificates

Source: https://ngrok.com/docs/api-reference/tlscertificates/list

Make a GET request to the ngrok API endpoint https://api.ngrok.com/tls_certificates to list all TLS certificates on the account. Each example sets the required headers ngrok-version: 2 and Authorization: Bearer <token>. The Go and Ruby examples print the response body; the Java example returns the response as a string.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ngrok.com/tls_certificates"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("ngrok-version", "2")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.ngrok.com/tls_certificates")
  .header("ngrok-version", "2")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.ngrok.com/tls_certificates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["ngrok-version"] = '2'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Multiple endpoints: ngrok start foo bar baz

Source: https://ngrok.com/docs/gateway/agent/expose-a-service

Starts multiple endpoints defined in the ngrok configuration file. The example starts endpoints named foo, bar, and baz.

```bash
ngrok start foo bar baz

```

--------------------------------

### Install ngrok Agent CLI on Windows

Source: https://ngrok.com/docs/getting-started/cloud-endpoints-quickstart

Install ngrok Agent CLI on Windows via the Windows App Store. Follow the direct installation guide if you cannot use the App Store.

```text
Install via the Windows App Store
```

--------------------------------

### Start vLLM server

Source: https://ngrok.com/docs/ai-gateway/custom-providers/vllm

Starts the vLLM OpenAI-compatible server with the specified model. Requires vLLM installed and a GPU with sufficient VRAM.

```bash
vllm serve meta-llama/Llama-3.2-8B-Instruct

```

--------------------------------

### Start the custom agent with python agent.py

Source: https://ngrok.com/docs/gateway/device-gateway/sdk

Starts the custom ngrok agent sample application built with the Python SDK. Run this after updating the domain on line 109 of agent.py.

```bash
python agent.py

```

--------------------------------

### bytes.size() example

Source: https://ngrok.com/docs/gateway/traffic-policy/macros

Shows how to use bytes.size() to get the number of bytes in a sequence. The example uses both method and function call syntax.

```plaintext
b'hello'.size() // 5
size(b'world!') // 6

```

--------------------------------

### Create IP Policy with Go

Source: https://ngrok.com/docs/api-reference/ippolicies/create

Go example using the standard library to create an IP policy. Sends a POST request with the required headers and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ngrok.com/ip_policies"

	payload := strings.NewReader("{\n  \"description\": \"<string>\",\n  \"metadata\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("ngrok-version", "2")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### ngrok config add-server-addr example

Source: https://ngrok.com/docs/gateway/agent/cli

Example of using add-server-addr with a specific server address.

```bash
ngrok config add-server-addr agent.example.com:443

```

--------------------------------

### GET /edges/https

Source: https://ngrok.com/docs/api-reference/edgeshttps/list

This code snippet documents the GET /edges/https endpoint, including its request headers, response schema, and example response.

```APIDOC
## GET /edges/https

### Description
List all HTTPS edges associated with the authenticated account.

### Method
GET

### Endpoint
https://api.ngrok.com/edges/https

### Parameters
#### Headers
- **ngrok-version** (string) - Required - API version, set to '2'.
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **https_edges** (array) - List of HTTPS edge objects.
  - **id** (string) - Unique identifier for the edge.
  - **description** (string) - Description of the edge.
  - **metadata** (string) - Metadata associated with the edge.
  - **created_at** (string) - Timestamp when the edge was created.
  - **uri** (string) - URI of the edge.
  - **hostports** (array of string) - Hostports associated with the edge.
  - **mutual_tls** (object) - Mutual TLS configuration.
    - **enabled** (boolean) - Whether mutual TLS is enabled.
    - **certificate_authorities** (array) - List of certificate authorities.
      - **id** (string) - Certificate authority ID.
      - **uri** (string) - URI of the certificate authority.
  - **tls_termination** (object) - TLS termination configuration.
    - **enabled** (boolean) - Whether TLS termination is enabled.
    - **terminate_at** (string) - Where TLS termination occurs.
    - **min_version** (string) - Minimum TLS version.
  - **routes** (array) - List of routes associated with the edge.
    - **edge_id** (string) - ID of the edge.
    - **id** (string) - Route ID.
    - **created_at** (string) - Timestamp when the route was created.
    - **match_type** (string) - Type of match for the route.
    - **match** (string) - Match pattern.
    - **uri** (string) - URI of the route.
    - **description** (string) - Description of the route.
    - **metadata** (string) - Metadata for the route.
    - **backend** (object) - Backend configuration.
      - **enabled** (boolean) - Whether backend is enabled.
      - **backend** (object) - Backend details.
        - **id** (string) - Backend ID.
        - **uri** (string) - Backend URI.
    - **ip_restriction** (object) - IP restriction configuration.
      - **enabled** (boolean) - Whether IP restriction is enabled.
      - **ip_policies** (array) - List of IP policies.
        - **id** (string) - Policy ID.
        - **uri** (string) - Policy URI.
    - **circuit_breaker** (object) - Circuit breaker configuration.
      - **enabled** (boolean) - Whether circuit breaker is enabled.
      - **tripped_duration** (integer) - Duration of tripped state.
      - **rolling_window** (integer) - Rolling window size.
      - **num_buckets** (integer) - Number of buckets.
      - **volume_threshold** (integer) - Volume threshold.
      - **error_threshold_percentage** (integer) - Error threshold percentage.
    - **compression** (object) - Compression configuration.
      - **enabled** (boolean) - Whether compression is enabled.
    - **request_headers** (object) - Request headers configuration.
      - **enabled** (boolean) - Whether request headers are enabled.
      - **add** (object) - Headers to add.
      - **remove** (array of string) - Headers to remove.
    - **response_headers** (object) - Response headers configuration.
      - **enabled** (boolean) - Whether response headers are enabled.
      - **add** (object) - Headers to add.
      - **remove** (array of string) - Headers to remove.
    - **webhook_verification** (object) - Webhook verification configuration.
      - **enabled** (boolean) - Whether webhook verification is enabled.
      - **provider** (string) - Provider name.
      - **secret** (string) - Secret for verification.
    - **oauth** (object) - OAuth configuration.
      - **enabled** (boolean) - Whether OAuth is enabled.
      - **provider** (object) - OAuth provider details.
        - **github** (object) - GitHub OAuth settings.
          - **client_id** (string) - GitHub client ID.
          - **client_secret** (string) - GitHub client secret.
          - **scopes** (array of string) - OAuth scopes.
          - **email_addresses** (array of string) - Allowed email addresses.
          - **email_domains** (array of string) - Allowed email domains.
          - **teams** (array of string) - Allowed teams.
          - **organizations** (array of string) - Allowed organizations.
        - **facebook** (object) - Facebook OAuth settings.
          - **client_id** (string) - Facebook client ID.
          - **client_secret** (string) - Facebook client secret.
          - **scopes** (array of string) - OAuth scopes.
          - **email_addresses** (array of string) - Allowed email addresses.
          - **email_domains** (array of string) - Allowed email domains.
        - **microsoft** (object) - Microsoft OAuth settings.
          - **client_id** (string) - Microsoft client ID.
          - **client_secret** (string) - Microsoft client secret.
          - **scopes** (array of string) - OAuth scopes.
          - **email_addresses** (array of string) - Allowed email addresses.
          - **email_domains** (array of string) - Allowed email domains.

#### Response Example
```json
{
  "https_edges": [
    {
      "id": "<string>",
      "description": "<string>",
      "metadata": "<string>",
      "created_at": "<string>",
      "uri": "<string>",
      "hostports": ["<string>"],
      "mutual_tls": {
        "enabled": true,
        "certificate_authorities": [{"id": "<string>", "uri": "<string>"}]
      },
      "tls_termination": {
        "enabled": true,
        "terminate_at": "<string>",
        "min_version": "<string>"
      },
      "routes": [
        {
          "edge_id": "<string>",
          "id": "<string>",
          "created_at": "<string>",
          "match_type": "<string>",
          "match": "<string>",
          "uri": "<string>",
          "description": "<string>",
          "metadata": "<string>",
          "backend": {
            "enabled": true,
            "backend": {"id": "<string>", "uri": "<string>"}
          },
          "ip_restriction": {
            "enabled": true,
            "ip_policies": [{"id": "<string>", "uri": "<string>"}]
          },
          "circuit_breaker": {
            "enabled": true,
            "tripped_duration": 123,
            "rolling_window": 123,
            "num_buckets": 123,
            "volume_threshold": 123,
            "error_threshold_percentage": 123
          },
          "compression": {"enabled": true},
          "request_headers": {
            "enabled": true,
            "add": {},
            "remove": ["<string>"]
          },
          "response_headers": {
            "enabled": true,
            "add": {},
            "remove": ["<string>"]
          },
          "webhook_verification": {
            "enabled": true,
            "provider": "<string>",
            "secret": "<string>"
          },
          "oauth": {
            "enabled": true,
            "provider": {
              "github": {
                "client_id": "<string>",
                "client_secret": "<string>",
                "scopes": ["<string>"],
                "email_addresses": ["<string>"],
                "email_domains": ["<string>"],
                "teams": ["<string>"],
                "organizations": ["<string>"]
              },
              "facebook": {
                "client_id": "<string>",
                "client_secret": "<string>",
                "scopes": ["<string>"],
                "email_addresses": ["<string>"],
                "email_domains": ["<string>"]
              },
              "microsoft": {
                "client_id": "<string>",
                "client_secret": "<string>",
                "scopes": ["<string>"],
                "email_addresses": ["<string>"],
                "email_domains": ["<string>"]
              }
            }
          }
        }
      ]
    }
  ]
}
```

### Error Handling
- **4XX** - Client error responses (e.g., 400, 401, 403, 404).
- **5XX** - Server error responses (e.g., 500, 502).
```

--------------------------------

### GET /app/users/{id}

Source: https://ngrok.com/docs/api-reference/applicationusers/get

This snippet documents the GET /app/users/{id} endpoint, including its parameters, request example, and response schema.

```APIDOC
## GET /app/users/{id}

### Description
Retrieves details about a specific application user by its unique identifier.

### Method
GET

### Endpoint
https://api.ngrok.com/app/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the application user.

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **ngrok-version** (string) - Required - API version, set to `2`.

### Request Example
```
curl --request GET \
  --url https://api.ngrok.com/app/users/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'ngrok-version: 2'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the application user.
- **uri** (string) - URI of the application user resource.
- **identity_provider** (object) - Contains identity provider details.
  - **name** (string) - Name of the identity provider.
  - **url** (string) - URL of the identity provider.
- **provider_user_id** (string) - User ID from the identity provider.
- **username** (string) - Username of the application user.
- **email** (string) - Email address of the application user.
- **name** (string) - Display name of the application user.
- **created_at** (string) - Timestamp when the user was created.
- **last_active** (string) - Timestamp of the user's last activity.
- **last_login** (string) - Timestamp of the user's last login.

#### Response Example
```
{
  "id": "<string>",
  "uri": "<string>",
  "identity_provider": {
    "name": "<string>",
    "url": "<string>"
  },
  "provider_user_id": "<string>",
  "username": "<string>",
  "email": "<string>",
  "name": "<string>",
  "created_at": "<string>",
  "last_active": "<string>",
  "last_login": "<string>"
}
```

#### Error Response (4XX)
- **status_code** (integer) - HTTP status code.
- **msg** (string) - Error message.
- **error_code** (string) - Error code.
- **details** (object) - Additional error details.

#### Error Response (5XX)
- **status_code** (integer) - HTTP status code.
- **msg** (string) - Error message.
- **error_code** (string) - Error code.
- **details** (object) - Additional error details.
```

--------------------------------

### ngrok config add-connect-url example

Source: https://ngrok.com/docs/gateway/agent/cli

Example of using add-connect-url with a specific connect URL.

```bash
ngrok config add-connect-url agent.example.com:443

```

--------------------------------

### Install Vercel AI SDK and OpenAI provider

Source: https://ngrok.com/docs/ai-gateway/sdks/vercel-ai-sdk

Install the Vercel AI SDK and the OpenAI provider package required for the examples on this page.

```bash
npm install ai @ai-sdk/openai

```

--------------------------------

### Start ngrok endpoint with `ngrok start demo-tls`

Source: https://ngrok.com/docs/gateway/agent/agent-tls-termination

Use this command to start an endpoint using the settings defined in your agent configuration file. Replace `demo-tls` with your endpoint name.

```bash
ngrok start demo-tls

```

--------------------------------

### Create and run a minimal Go HTTP server

Source: https://ngrok.com/docs/getting-started/go

Creates a minimal Go HTTP server on port 8080 and runs it with `go run service.go`. The server responds with "Hello from Go HTTP Server!" and prints a startup message.

```go
package main

import (
	"fmt"
	"net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello from Go HTTP Server!")
}

func main() {
	http.HandleFunc("/", handler)

	fmt.Println("Starting server at http://localhost:8080")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		fmt.Println("Server failed:", err)
	}
}

```

```bash
go run service.go

```

--------------------------------

### GET HTTPS Edge Response Body

Source: https://ngrok.com/docs/api-reference/edgeshttps/get

Example JSON response body returned by the GET /edges/https/{id} endpoint. Contains the edge configuration including routes, TLS termination, mutual TLS, and OAuth provider settings. Field values are placeholders shown as <string> or numeric examples.

```json
{
  "id": "<string>",
  "description": "<string>",
  "metadata": "<string>",
  "created_at": "<string>",
  "uri": "<string>",
  "hostports": [
    "<string>"
  ],
  "mutual_tls": {
    "enabled": true,
    "certificate_authorities": [
      {
        "id": "<string>",
        "uri": "<string>"
      }
    ]
  },
  "tls_termination": {
    "enabled": true,
    "terminate_at": "<string>",
    "min_version": "<string>"
  },
  "routes": [
    {
      "edge_id": "<string>",
      "id": "<string>",
      "created_at": "<string>",
      "match_type": "<string>",
      "match": "<string>",
      "uri": "<string>",
      "description": "<string>",
      "metadata": "<string>",
      "backend": {
        "enabled": true,
        "backend": {
          "id": "<string>",
          "uri": "<string>"
        }
      },
      "ip_restriction": {
        "enabled": true,
        "ip_policies": [
          {
            "id": "<string>",
            "uri": "<string>"
          }
        ]
      },
      "circuit_breaker": {
        "enabled": true,
        "tripped_duration": 123,
        "rolling_window": 123,
        "num_buckets": 123,
        "volume_threshold": 123,
        "error_threshold_percentage": 123
      },
      "compression": {
        "enabled": true
      },
      "request_headers": {
        "enabled": true,
        "add": {},
        "remove": [
          "<string>"
        ]
      },
      "response_headers": {
        "enabled": true,
        "add": {},
        "remove": [
          "<string>"
        ]
      },
      "webhook_verification": {
        "enabled": true,
        "provider": "<string>",
        "secret": "<string>"
      },
      "oauth": {
        "enabled": true,
        "provider": {
          "github": {
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "email_addresses": [
              "<string>"
            ],
            "email_domains": [
              "<string>"
            ],
            "teams": [
              "<string>"
            ],
            "organizations": [
              "<string>"
            ]
          },
          "facebook": {
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "email_addresses": [
              "<string>"
            ],
            "email_domains": [
              "<string>"
            ]
          },
          "microsoft": {
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "email_addresses": [
              "<string>"
            ],
            "email_domains": [
              "<string>"
            ]
          }
        }
      }
    }
  ]
}

```
Tokens:
Raw