# Authentication and API keys

Bearer API keys, read-only versus full keys, per-key daily credit caps, rotating a key, and keeping keys out of browsers.

Source: https://magistermarketing.com/docs/api/authentication

Every request sends an API key as a bearer token:

```http
Authorization: Bearer mm_live_...
```

A missing, unknown or revoked key answers **401** `not_authenticated`, the same for all three so a probe learns nothing about which keys exist.

**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](https://magistermarketing.com/docs/api/endpoints) 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](https://magistermarketing.com/docs/api/credits-and-billing), 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](https://magistermarketing.com/docs/api/jobs-and-webhooks) 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.