> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API governance model: the org default + per-key override self-serve model

> The conceptual model behind Developer → API governance: one org-wide rate-limit and monthly-quota tier every API key inherits, per-key overrides that win field by field, cache invalidation that puts a saved value into force on the key's next request, and how the console reads live usage and headroom against the tier.

# 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](/guides/developer-api-governance-console); for the
per-endpoint request tables see [Rate limits](/guides/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](/concepts/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](/guides/api-key-usage-limits).

## 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](/concepts/roles-teams-permissions) does.

## See also

* [Rate-limit and cooldown taxonomy](/concepts/rate-limit-and-cooldown-taxonomy) — the limiter family this page configures (Family 1)
* [Rate limits](/guides/rate-limits) — per-endpoint request tables and retry patterns
* [API governance console](/guides/developer-api-governance-console) — click-through walk of the dashboard surface
* [Per-API-key usage limits and spend alerts](/guides/api-key-usage-limits) — the per-key usage-limits API guide
* [API key IP allowlist](/guides/api-key-ip-allowlist) — the other per-key admission control
* [API keys: end to end](/guides/api-keys-end-to-end) — the key lifecycle the overrides hang off
* [API analytics reader](/guides/api-analytics-reader) — the metrics surface the same usage counters feed
* [Rate limits & cooldown troubleshooting](/troubleshooting/rate-limits) — the live 429 handling steps