API Keys

An API key is a long-lived secret that authenticates a non-browser caller to the Mimir HTTP API. The most common use is a CI pipeline, provisioning script, or in-house dashboard that pulls host or alert data from Mimir on a schedule — anything that can’t (or shouldn’t) sign in interactively. Each key is bound to your user account, so the calls it makes carry your permissions: an Operator’s key can read hosts and alerts; an Admin’s key can also flip rollout percentages and manage other users.

This panel is the only place to mint keys, and the only place to revoke them. There’s no separate service-account model in v1 — every key is a user-attributed credential.

What you get

Two surfaces on the same panel:

Your keys — a table of every key you’ve ever minted, with the name you gave it, when it was created, and when it was last used (or Never if no request has ever come in with that key).
Generate key — a form at the bottom of the panel with a single New key name field and a Generate key button.

Every row in the table has a Revoke action on the right edge. Revocation is immediate — there’s no grace period — and a confirmation modal protects against accidental clicks.

How to mint a key

Open Settings → API Keys.
Type a memorable name into New key name. Suggested patterns: ci-pipeline-staging, terraform-prod, <your-name>-laptop-cli. Names are free-form text; they show up in audit logs and help future-you remember which key is which.
Click Generate key. A green-bordered reveal card appears at the top of the panel:

Key created. Copy it now — it will not be shown again. <the secret value> [Copy to clipboard]
Click Copy to clipboard and paste the value into your CI secret store / ~/.netrc / wherever it needs to live. Mimir hashes the value server-side; once you leave this page, there is no way to retrieve the plaintext again.

A toast confirms API key created. The new row also appears in the Your keys table below — with the secret value masked, of course.

If you close the reveal card without copying, the key is still active in the database — you just can’t see the secret anymore. Revoke it and mint a new one.

How to revoke a key

Find the row for the key you want to kill in the Your keys table.
Click Revoke on the right edge.
Confirm in the modal:

Revoke API key “ci-pipeline-staging”? Any services using this key will lose access immediately.
Click Revoke.

The row disappears from the table immediately. The next request that authenticates with the revoked value gets 401 Unauthorized. There is no soft-delete or “paused” state — revocation is the only off switch, and it’s one-way.

If you revoked the wrong key by mistake, you’ll need to mint a new one and update the calling service. The old secret value is hashed server-side and gone forever once the row is deleted.

Using a key with the API

Pass the secret in the Authorization header as a bearer token:

Authorization: Bearer <your-key>

That’s it. Every Mimir API endpoint accepts either a session cookie (set when you log in via the web UI) or this header. The header has no expiry, so the key stays valid until you revoke it.

For programmatic callers, the typical pattern is:

curl -H "Authorization: Bearer $MIMIR_API_KEY" \
     https://your-mimir-host/api/v1/hosts

The mimir-cli tool reads MIMIR_API_KEY from the environment so shell scripts don’t have to handle the header themselves.

What an API key can do

A key carries the role the minting user had at the moment the key was minted. If you minted as an Operator, the key is an Operator’s key — it can list hosts, view alerts, launch hunts (subject to your role’s caps), and otherwise do everything you can do in the browser.

Role changes invalidate keys. If an admin later promotes you to Admin, or demotes you, or changes your password, your existing keys stop working — the next request returns 401 Unauthorized: api key revoked. You’ll need to mint new keys after the role change. Mimir versions every account’s authorization state and refuses keys that were minted under an older version, so the keys can’t silently carry elevated (or stale) permissions across a role transition.

If your user is suspended or has its status flipped to non-active, every key attributed to that user gets 403 forbidden: account suspended or deleted on the next request. There’s no orphan “service account” model where a deleted user leaves keys behind. Mint keys under the account that should own the integration long-term, and re-mint after any change to that account’s role, status, or password.

Naming conventions worth adopting

The name is the only context that travels with the key. Two patterns that scale well across a team:

<service>-<environment> — terraform-staging, ci-prod, grafana-dev. Clean for infrastructure-as-code shops.
<owner>-<purpose> — alice-laptop-cli, bob-test-script, oncall-rotation-fetcher. Better when humans, not pipelines, are the consumers.

Either way, avoid generic names like key1 or my-key. Within six months you’ll have five of them and won’t remember which is which.

Troubleshooting

The “Generate key” button doesn’t do anything. The form requires a non-empty name. If you typed only spaces, the trim filter rejects the submission silently. Type at least one non-whitespace character.

The reveal card showed for a moment then disappeared. It only goes away when you click the ✕ or navigate elsewhere — there’s no auto-dismiss. If you missed it entirely (e.g. browser tab loses focus mid-submit), the key is live but unrecoverable. Revoke and re-mint.

My script is getting 401 even though the key looks right. Three common causes:

The key was revoked by you (or another admin acting on a compromise report). Check this panel for the row.
Your user was deleted or demoted. If your browser session also stopped working, this is the explanation.
The header is misformatted — missing the Bearer prefix, or an extra newline / leading space. The server expects exactly Authorization: Bearer <key>.

Last-used timestamp says Never even though I’m using the key. The column shows the last successful authentication. If your requests are getting 401s for any reason (revoked, malformed header, network proxy stripping headers), the column won’t update. Run one known-good request, then refresh the page.

Permissions

Anyone with a Mimir account can mint keys for themselves (this panel is not admin-only — unlike Users, Enrollment, SSO, and the two update panels). The Your keys table is strictly per-user: even admins only see their own keys here.

If a teammate’s key is compromised, the teammate has to revoke it from their own session — admins cannot revoke another user’s keys from this panel. The Mimir GUI does not currently offer a “disable-user” or “delete-user” affordance either, so a key from an unreachable teammate’s account requires direct database intervention by whoever operates your Mimir deployment. Treat keys with the same seriousness you’d treat the password they were minted under.