Skip to main content

​
API governance model

Every API key in your workspace is bound by a request-rate cap and, if you set one, a monthly request quota. Orbit ships platform defaults for both — generous enough that well-behaved integrations never touch them — and exposes one org-wide tier you set yourself, plus per-key overrides that beat the org tier field by field. The whole model is self-serve from Developer → API governance in the dashboard (or the /developer/governance API): an owner, admin, or developer reads live usage, picks a value, and the change is enforced on the key’s very next request. This page explains the model — why it is two layers, what an override actually does, and how to read usage against it. For the click-through walk of the console see API governance console; for the per-endpoint request tables see Rate limits.

​
Why org defaults + per-key overrides exist

Two failure shapes drove the design:
  • One noisy key spends the whole workspace’s throughput. A stuck retry loop or a leaked credential used to take down every integration in the org; each key now carries its own window, so one bad key trips its own cap and its own quota, and its siblings keep answering.
  • Raising a cap used to be a support ticket. The console puts the org default and the per-key override behind an owner/admin/developer write — with live usage and headroom on the same page — so the person who needs a higher cap reads the current headroom and sets the new value in the same visit, the same self-serve posture Twilio and Stripe expose.
Governance is inbound admission control only: it bounds how often a key may call the API. It never originates traffic, and it never touches which carrier or route an outbound send takes.

​
The org default tier

The org-wide default is the tier every API key inherits unless the key carries its own override. Three knobs, each independent:
  • Requests per minute — throughput: how many requests the key may make inside each one-minute window. Exceeding it rejects the excess calls with 429 until the window rolls over.
  • Monthly request quota — volume: a hard ceiling on requests counted from the 1st of the month (UTC). Exceeding it rejects every further call with 429 until the month resets.
  • Usage-alert threshold — an advisory percent of the monthly quota. Crossing it only flags the key in the console; it never blocks traffic. The quota is the thing that blocks.
Every value is bounded. A value of 0 is rejected (a zero cap would hard-block the key — revoke the key instead), and the platform’s upper bounds (60,000 requests/minute; 1,000,000,000 requests/month) are the same ones the console shows in the Org-wide default card, so an out-of-range value cannot be saved. Headroom is the remaining slice of the quota — limit − used, with usage_percent beside it — shown as a bar per key, so “how much is left” is a read, not a computation.

​
Per-key overrides (override and clear)

An override carries the same dimensions as the org tier — requests per minute, monthly quota, and a monthly spend limit — and wins field by field: a key that overrides only its rpm still inherits the org’s monthly quota. Setting every field to null clears the override and the key falls back to the org tier. Both write routes — the Org-wide default card and the per-key Override dialog — invalidate the cached governance config server-side the moment the write completes. The rate-limit and quota guards resolve through that cache, so the new value is in force on the key’s next request: no propagation window, no “wait a minute” step. To bound a key’s cached read-modify-write the services also read-modify-write through the same cached resolver.

​
How governance composes with the limiter taxonomy

Governance configures Family 1 of the Rate-limit and cooldown taxonomy — the per-API-key request caps that guard the API surface. It is the configurable, self-serve tier of that family; it interacts with nothing in Families 2–4 (throughput ceilings, frequency caps, recipient cooldowns). When a 429 returns, read the error code first: a RATE_LIMITED / RATE_LIMIT_EXCEEDED shape against the API surface is the family this page configures. A per-key spend limit composes with the same resolve — see Per-API-key usage limits and spend alerts.

​
Where to read usage and headroom

The dashboard renders the resolve in one place under Developer → API governance:
  • Org-wide default card — the tier and its platform upper bounds, with an editable form.
  • Per-key table — one row per active key: effective limits and the override badge, live requests this minute, requests this month, the headroom bar (limit − used percent), and a status badge that flags alerting or over_quota.
  • Chart + table from the API — the /developer/governance read returns month-to-date spend per key (aggregated from request metrics) beside quota usage, so the same JSON drives both the console table and any polling script.
Usage counters are live at the moment of the read — the console holds a 10-second cache, so a manual Refresh re-reads them without pegging keep-alive costs on a background poll.

​
Safe operations

Governance writes are reversible and idempotent: a write only changes the fields it names, null clears a field back to the org default or the platform default, and the write route audit-logs the before/after on every change. Because a per-key override beats the org default field by field, a bad key can be tightened without touching the org tier — and cleared the same way when the incident closes. The org default is only ever inherited; clearing the override restores it. Writes require the owner, admin, or developer role, so the console and the API bound the same roles the dashboard does.

​
See also