From zero to enforced limits.

Quickstart

Three commands. Install the CLI, log in, and push a policy. Your limits are live at the edge before the last command finishes.

# 1. install
npm install -g @throttlebox/cli

# 2. authenticate (opens a browser)
tb login

# 3. push your first policy in monitor-only mode
tb policy push ./throttlebox.yaml --mode monitor

A minimal policy file looks like this:

name: public-api
key: header:x-api-key
rules:
  - match: "/v1/*"
    strategy: sliding-window
    limit: 600        # requests
    window: 1m
    burst: 120

Authentication

Every API call carries a project secret in the Authorization header. Secrets are scoped per environment, so a staging key can never mutate a production policy.

Authorization: Bearer tb_live_8f3a...  # production
Authorization: Bearer tb_test_21bc... # sandbox

Rotate a secret from the dashboard or with tb keys rotate. The old secret keeps working for a 24 hour grace window.

Your first request

Ask ThrottleBox whether a given key may proceed. In proxy mode you never call this yourself - it is useful when you want to enforce limits inside your own code.

const res = await fetch("https://api.throttlebox.dev/v1/check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TB_SECRET}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ policy: "public-api", key: apiKey })
});

const { allowed, remaining } = await res.json();

import os, requests

res = requests.post(
    "https://api.throttlebox.dev/v1/check",
    headers={"Authorization": f"Bearer {os.environ['TB_SECRET']}"},
    json={"policy": "public-api", "key": api_key},
    timeout=2,
)

allowed = res.json()["allowed"]

body, _ := json.Marshal(map[string]string{
    "policy": "public-api",
    "key":    apiKey,
})

req, _ := http.NewRequest("POST", "https://api.throttlebox.dev/v1/check", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("TB_SECRET"))

resp, err := http.DefaultClient.Do(req)

Endpoint reference

Response headers

When ThrottleBox proxies your traffic it adds the standard headers below, so well-behaved clients can back off before they are blocked.

RateLimit-Limit: 600
RateLimit-Remaining: 118
RateLimit-Reset: 27
Retry-After: 27          # only on 429 responses

Changes to any of this are recorded on the changelog.