Authentication

Send both headers on every request:

They are required together, and the organization id must be the organization the key belongs to. A mismatch is rejected with 401 — it is not silently reinterpreted as the key's own organization, because a caller that sent the wrong id is a caller whose next request is also wrong.

Scope

A credential is scoped to exactly one organization, and that scope is enforced at the data layer rather than by request validation. There is no request parameter that widens it, which is why organizationId never appears in a request body: an operation cannot be pointed at data the credential does not already reach.

Handling keys

• Keep the key server-side. It is a bearer credential — anyone holding it is you.
• Rotate by requesting a new key, moving traffic to it, then retiring the old one. Both are live during the overlap, so a rotation needs no downtime window.
• If a key is exposed, tell us immediately; a compromised key is revoked, not rotated on a schedule.

What a failure looks like

• 401 — the key is missing, unknown, revoked, or does not match the organization id.
• 429 — the credential is over its rate limit. See Errors and retries.