Authentication and API keys

Who creates keys — organization owners and admins, in Settings → Developers → API keys. Members see each key's name and usage, never the key. The full key is shown once, when it is created; Magister stores only its hash.

What a key acts as — a key acts for its organization as the person who created it, and is billed to that organization's API credits. It is revoked when that person leaves the organization, so create production keys as someone who will stay.

Full or read only — a full key has the read and write scopes and can start work that spends credits. A read-only key has only read: it can read your balance and jobs and run the free endpoints, and it can never spend credits. A call that needs a scope the key lacks answers 403 not_authorized with required_scope. The Endpoints reference gives each endpoint's scope.

Daily credit cap — give a key an optional cap when you create it. A paid call is refused when the key's spend today (UTC), plus what its running requests hold, plus the new request's hold, would pass the cap: it answers 429 rate_limited with reason: key_daily_cap_reached and retry_after_seconds until 00:00 UTC. A request whose hold alone is above the cap can never start on that key, so it answers 402 limit_reached with reason: key_daily_cap_too_low, estimated_credits and daily_cap_credits, and waiting does not help: under a 100-credit cap, for example, a site audit (which holds 240) never starts. Set the cap above the largest hold the key needs. The cap is per key; the organization's balance still applies to all of them.

Limits for the whole organization — 60 requests a minute and 5 running jobs, however many keys you have. Past either, the API answers 429 with retry_after_seconds and a Retry-After header.

Rotating a key — create the new key, deploy it, confirm its calls in Requests, then Revoke the old one. A revoked key stops working at once; its past usage stays in Usage and Requests. Revoke immediately if a key leaks. Jobs can be polled only with the key that started them, so let running jobs finish (or note their results) before you revoke. Once a key is revoked, nothing more goes to the webhook_url its jobs named, not even for a job still running; your registered endpoints still get every event.

Never in a browser — a key spends your organization's credits. Keep it in a server-side secret store or environment variable; never put it in web pages, mobile apps or a public repository. Use one key per system so you can revoke one without the others.