Server API

teitunnel serve runs a server's tunnels and offers a web dashboard and a small JSON API next to it (see Servers and containers). Use the API to add and remove routes from deploy scripts, read route status and uptime for monitoring, or look at captured requests. Every change goes through the same reviewed plan as in the app: you preview it, then apply exactly that plan.

The machine-readable description (OpenAPI 3.1) is at /api/openapi.json on the server, without signing in.

Start the serverCopy Anchor Link

teitunnel serve --set-password        # once: the dashboard password, read from the terminal
teitunnel serve                       # listens on 127.0.0.1:8765

serve refuses to start without a password, and refuses a non-loopback address without --allow-remote. Instead of exposing the port, you can also publish the dashboard through Teitunnel itself on a route with a login.

AuthenticationCopy Anchor Link

Automation uses API keys. Create one on the server and send it as a bearer token:

teitunnel api-key create deploy       # printed once; store it as a secret
teitunnel api-key list                # ids and names only
teitunnel api-key revoke 3            # by id

Authorization: Bearer ttk_…

Keys start with ttk_ and are stored only as hashes, so a lost key can't be shown again: revoke it and create another. The same keys work for /mcp.

The browser dashboard signs in with the password instead: POST /api/login sets a session cookie (HttpOnly, SameSite=Strict, 12 hours). Every change made with a session must also send an X-Teitunnel header (any value), which a cross-site form can't send. API keys don't need it.

EndpointsCopy Anchor Link

Messages in answers (plan steps, warnings, errors) are plain English text.

GET /api/overviewCopy Anchor Link

{
  "machine": "<this machine's name>",
  "accounts": [
    { "id": "…", "name": "<account name>", "overview": { "…": "tunnels, routes, status" }, "error": null }
  ],
  "shares": []
}

An account whose overview couldn't be read has overview: null and the reason in error.

GET /api/analyticsCopy Anchor Link

Needs Zone · Analytics · Read on the account's token (Analytics). Answers 403 without it, and 429 when Cloudflare's analytics rate limit is reached.

GET /api/uptimeCopy Anchor Link

Without parameters: every route on this machine with its uptime over 24 hours, 7 days and 30 days, p95 response time and any open incident. With hostname (and path, range): one route's status strip, response times and incidents; 404 if this machine doesn't serve it.

GET /api/trafficCopy Anchor Link

Requests the inspector captured: shares started over /mcp, and this machine's recent history. Read-only; credentials are always masked, and the API can't reveal them.

The answer has items (id, tap, method, host, path, status, durationMs, sizes, kind, state, webhook) and next. GET /api/traffic/{id} returns one exchange with headers, bodies, timings and the webhook signature check.

Making a changeCopy Anchor Link

A change is two calls. The preview returns the plan and its fingerprint; applying sends the same change with that fingerprint. If anything changed in Cloudflare in between, apply answers 409 and nothing is changed: preview again.

curl -s -X POST http://127.0.0.1:8765/api/preview \
  -H "Authorization: Bearer $TEITUNNEL_API_KEY" -H 'Content-Type: application/json' \
  -d '{"accountId":"<account id>","change":{"type":"addRoute","route":{"hostname":"api.yourhost.com","origin":"8080","path":null,"access":null}}}'

{
  "steps": [
    { "kind": "putConfig", "description": "…", "command": null },
    { "kind": "createRecord", "description": "…", "command": null }
  ],
  "warnings": [],
  "requiresConfirmation": false,
  "fingerprint": "…"
}

curl -s -X POST http://127.0.0.1:8765/api/apply \
  -H "Authorization: Bearer $TEITUNNEL_API_KEY" -H 'Content-Type: application/json' \
  -d '{"accountId":"<account id>","change":{…the same change…},"fingerprint":"…","confirmed":false}'

Get the account id from /api/overview or teitunnel accounts --json.

Change typesCopy Anchor Link

change is an object with a type. Fields are camelCase.

A route:

• hostname: on one of the account's domains.
• origin: a port ("3000"), host:port, or a URL ("http://localhost:3000").
• path: a path regex such as "^/api", or null.
• access: { "emails": ["team@yourhost.com"], "emailDomains": ["yourhost.com"] } to require a login, or null. Add "github": ["teispace/Developers"] for GitHub teams and "signIn": "github" or "google" to allow only that login method. On updateRoute, null removes the login Teitunnel added.
• options: origin settings (the same as the CLI's origin flags, camelCase), or leave it out for cloudflared's defaults (on updateRoute, leaving it out keeps the current ones).

protection for protectHostname (Edge protection); an empty object removes Teitunnel's rules:

{
  "bots": "challenge",
  "aiCrawlers": true,
  "rateLimit": { "requests": 100, "period": 60, "action": "block" },
  "requestHeaders": [{ "name": "Cookie", "op": "remove" }],
  "responseHeaders": [{ "name": "X-Robots-Tag", "op": "set", "value": "noindex" }],
  "bypassCache": false
}

bots is off, challenge or block; bypassCache: true stops Cloudflare caching the hostname's responses (it needs the Cache Rules permission); period is one of 10, 60, 120, 300, 600 or 3600 seconds; action is block or challenge; op is set, add (response headers only) or remove.

tunnelId (next to accountId) picks one of the machine's tunnels; without it, the default tunnel, or the tunnel carrying an existing route.

ErrorsCopy Anchor Link

Errors are JSON: { "error": "…" }.

SecurityCopy Anchor Link

• Listens on loopback unless --allow-remote. No CORS headers are ever sent.
• Every response carries a strict Content Security Policy, X-Frame-Options: DENY, Referrer-Policy: no-referrer and Cache-Control: no-store.
• No secret is ever returned: not tokens, not keys, not captured credentials.
• /mcp refuses requests with an Origin header unless it's allowed with --mcp-allow-origin, accepts only a loopback Host unless the server listens remotely, and refuses repeated bad keys from one address for a while.

RelatedCopy Anchor Link