Skip to content

Auth & limits

The broker's access model is the security core of the whole capability plane: tokens, scopes, and budgets — the same ideas as cloud IAM, applied to AI capabilities.

Request authentication

Authorization: Bearer <BROKER_TOKEN>
X-Blackrack-Gateway: <tenant-slug>
X-Blackrack-Request-Id: <optional stable request id>
  • The gateway header must match the slug bound to the token — a token cannot be replayed under another tenant's identity.
  • X-Blackrack-Request-Id is echoed on responses (or generated when absent) so a single user request can be correlated across gateway, broker, and provider attempts.

Token shape

A broker token is a random opaque value bound to a tenant and an explicit scope list with per-capability daily limits:

{
  "tokens": {
    "brgw_<opaque>": {
      "slug": "<tenant>",
      "scopes": [
        "search:brave",
        "search:web",
        "search:perplexity",
        "scrape:web",
        "audio:transcribe",
        "tts:speak",
        "voice:telnyx",
        "voice:telnyx:hangup",
        "mcp:scrapling"
      ],
      "limits": {
        "search:brave":      { "requests_day": 100 },
        "search:web":        { "requests_day": 200 },
        "search:perplexity": { "requests_day": 20,  "units_day": 100000 },
        "scrape:web":        { "requests_day": 50,  "units_day": 41943040 },
        "audio:transcribe":  { "requests_day": 50 },
        "tts:speak":         { "requests_day": 100 },
        "voice:telnyx":      { "requests_day": 25 },
        "mcp:scrapling":     { "requests_day": 50,  "units_day": 41943040 },
        "browser:cloud": {
          "requests_day": 5,
          "max_session_cost_usd": 0.25,
          "max_raw_timeout_minutes": 15
        }
      }
    }
  }
}

Key properties:

  • Scopes are capabilities, not endpoints — the same token shape serves search, voice, browser, and MCP capabilities.
  • Limits are per tenant per day, enforced server-side; units_day budgets token-heavy capabilities (research, scraping) separately from request counts.
  • Browser use gets cost caps: max_session_cost_usd is injected into the upstream browser agent's own cost limit, and max_raw_timeout_minutes caps raw/CDP sandboxes.
  • Ownership is token-bound: optional browser_owner pins browser resources to one (agent, user) pair and ignores caller-supplied owner headers; an optional browser_allowed_agents allowlist rejects everything else.

What the broker enforces per request

  1. Token exists and is active.
  2. Gateway slug matches the token's slug.
  3. The requested capability is in the token's scope list.
  4. The daily request and unit budgets for that capability have not been exhausted.
  5. For browser: cost/time caps, owner binding, and agent allowlist.
  6. For MCP/HTTP proxy targets: service registered + host allowlisted + byte caps + origin policy.
  7. For payment-like data: Luhn-validated card numbers and CVV mentions are rejected before anything reaches a provider.

If any check fails, the request fails closed — no partial pass-through.

Usage & audit

Every accepted call records a usage event: provider, capability, tenant, units, estimated cost, latency, status, and a content hash where applicable. The broker deliberately does not log raw query text, transcripts, TTS text, phone-message bodies, or provider keys.

Operators can query /v1/usage/summary and /v1/limits/status to see who is spending what — and the data feeds cost decisions (which rung of the search ladder deserves more budget, which tenant needs a cap review).

Runtime notes

  • Broker tokens are provisioned per tenant and stored in the cluster secrets, never in git (SealedSecrets only).
  • /readyz separates core_errors (HTTP 503) from degraded_capabilities (optional providers missing) so a single optional provider can never remove the broker from the service mesh.
  • Circuit breakers open per provider/capability on repeated upstream failure, and the provider ladders skip open circuits automatically.