Gateway auth, tenant context, and common headers

RouterBrain /v1/* (except documented probes) resolves tenant context from the tenant API key on the data plane, then ties in model allowlists, upstream key binding, usage reporting, etc. This page covers what callers need and what to watch behind proxies; table-level details are in your deployment README and service source.

Authorization: Bearer

• Authorization: Bearer <plaintext key> must match the tenant API key (often sk- prefix).
• Keys are matched in tenant_api_keys on key_text with enabled = true; disabled or deleted → 401 (same outward policy as missing Bearer, per implementation).

Optional: API key IP binding (IPv4)

If the key has rows in tenant_api_key_allowed_ips, IPv4 allowlisting applies:

• Client IPv4 from ctx.ip (including normalizing ::ffff:x.x.x.x to IPv4).
• Missing IPv4 or not in list → 403, error.code === "ip_not_allowed".
• No rows → no IP restriction.

Reverse proxies: whether the service sees the proxy or the real client depends on Koa / deployment trust for X-Forwarded-For. If allowlisting mis-fires, check header forwarding and trusted hop count.

Default business headers (SDK-aligned)

With @routerbrain/sdk, pass defaultHeaders in the constructor (per-request overrides may use RequestOptions, depending on version):

You can send the same headers on raw HTTP to align with logs and billing fields.

See also

• Gateway quickstart (direct HTTP)
• Models and routing
• SDK quickstart (defaultHeaders)

Back to docs home