Built for agents.

Mint a key with a cap

curl -X POST "$API/tokens" \
    -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "claude-agent-prod",
      "ttlHours": 720,
      "bandwidth": 100,
      "tunnelQuota": 10,
      "monthlyBudgetUsdCents": 5000
    }'

The response is the only place the full key value appears:

{
  "id": "abc-123",
  "name": "claude-agent-prod",
  "apiKey": "mtk_xxx_full_value_here",
  "monthlyBudgetUsdCents": 5000
}

Adjust the cap (owner only)

# Raise / lower
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": 1000 }'

# Uncap
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": null }'

# Freeze all spend (incident response)
curl -X PUT "$API/tokens/$NONCE/budget" \
    -H "Authorization: Bearer $JWT" \
    -d '{ "monthlyBudgetUsdCents": 0 }'

$NONCE is the first 16 hex chars of the token's nonce, visible in the GET /tokens list. The budget is charged on the agent transport at tunnel-registration time — an over-budget agent's mytunnel register is rejected with a BUDGET_EXCEEDED protocol reason, and the agent should surface that to its operator rather than retry.

Provision (GitHub)

curl -X POST "$API/webhook-receivers" \
    -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "validator": "github",
      "secret": "whsec_from_github_webhook_config",
      "name": "PR events for my-bot"
    }'

Paste the returned url into the repo's webhook settings. GitHub starts firing signed POSTs.

Generic HMAC-SHA256 (Linear, Vercel, GitLab, your app)

curl -X POST "$API/webhook-receivers" \
    -H "Authorization: Bearer $JWT" \
    -d '{
      "validator": "generic_hmac_sha256",
      "secret": "<vendor-secret>",
      "signature_header": "x-my-vendor-signature",
      "signature_encoding": "hex",
      "name": "Linear issue events"
    }'

signature_encoding is "hex" or "base64".

Poll validated events

curl "$API/webhook-receivers/$ID/events?limit=50" \
    -H "Authorization: Bearer $JWT"

Each event carries a signature_valid flag — false means the signature didn't verify; we store it so you can alert, but don't trust the body. Use the received_at of the last event you saw as a cursor via ?since=<timestamp>.

dodo as a validator value is accepted by the schema but not yet wired — Dodo billing events flow through the dedicated /webhooks/dodo endpoint, not the tenant receiver primitive.

Envelope shape

{
  "error": "TTL_TOO_LONG",
  "message": "ttl_seconds exceeds plan max of 86400 seconds for plan 'free'",
  "next_action": "FIX_REQUEST_AND_RETRY",
  "request_id": "9a3f-..."
}

Rate-limit and internal-error responses additionally carry a retry_after_ms hint so an agent can self-throttle without polling.

Verified codes + directives

Older endpoints still return the legacy shape { "error": "snake_case", "message": "…" } (e.g. missing_bearer, upgrade_required) without next_action. These migrate to the structured envelope as they're touched. Always handle both: presence of next_action tells you which shape you got.

Budget enforcement is on the transport, not REST

When an agent's spend cap is hit, the rejection happens at tunnel-registration time over the agent transport (the mytunnel register fails with a BUDGET_EXCEEDED protocol reason), not as an HTTP error from POST /tunnels. An agent that sees this should stop its loop and request human approval — the cap won't move until an owner raises it.