Policies & Approval

Policies control which requests are auto-approved and which require human approval via Telegram.

Policy Evaluation Order

When a request arrives, the proxy evaluates policy rules in this order:

URL patterns — if the target URL contains any auto_approve_urls substring, auto-approve regardless of HTTP method
Method rules — if the HTTP method is in auto_approve, auto-approve. HEAD follows GET policy
Require approval — if the method is in require_approval, require human approval
Default — if the method isn’t in either list, require approval (fail closed)

policies:
  slack:
    auto_approve: ["GET"]
    require_approval: ["POST", "PUT", "DELETE"]
    auto_approve_urls:
      - "/conversations.list"    # auto-approve even though it uses POST
      - "/users.list"

In this example, POST /conversations.list is auto-approved (URL pattern match), but POST /chat.postMessage requires approval (method rule).

No Policy = Fail Closed

If a credential has no entry in the policies section, all requests require approval. This is intentional — you must explicitly opt in to auto-approval.

Telegram Approval

When a request requires approval, the proxy sends a message to your Telegram chat with:

Agent name and credential being used
HTTP method and target URL
Request body preview
Approve and Deny inline buttons

The proxy blocks until someone taps a button or the timeout expires (default 5 minutes, configurable via approval.timeout_seconds).

Long-Polling (Default)

The proxy polls Telegram’s getUpdates API with a 30-second server-side timeout. This works behind firewalls and NAT without exposing a public URL.

Webhook Mode

For production deployments with a public URL, you can configure Telegram webhooks via the Telegram Bot API. The proxy handles callbacks at POST /telegram/webhook.

Per-Credential Approval Routing

You can restrict who can approve requests and route approval messages to different Telegram chats per credential.

policies:
  production-db:
    require_approval: ["GET", "POST", "PUT", "DELETE"]
    approval:
      allowed_approvers:
        - "123456789"    # Telegram user ID — only this person can approve
        - "987654321"
      telegram:
        chat_id: "-100987654321"  # Send to a different chat than the default

allowed_approvers

A list of Telegram user IDs. When set:

Only listed users can tap Approve/Deny
Other users who tap the buttons get an “unauthorized” alert
Empty list (default) = anyone in the chat can approve

Per-credential chat_id

Overrides the global TELEGRAM_CHAT_ID for this credential’s approval messages. Useful for routing sensitive credentials to a restricted channel.

Rate Limiting

Per-agent rate limiting is configured in the agents section:

agents:
  my-agent:
    credentials: [slack, github]
    rate_limit_per_hour: 100

When exceeded, the proxy returns 429 Too Many Requests. Omit rate_limit_per_hour for unlimited requests.

CLI Reference Deployment