API keys and credentials

How osk_ agent keys are minted, stored, and rotated, what a leaked key exposes, and why the console API has no personal access tokens.

Last updated

On this page

The only credentials your account handles are the per-server agent keys — strings starting with osk_ — that let the console read your servers' metrics. Keys are minted on the server, stored server-side in the console, and rotated from the server.

The osk_ key lifecycle

  1. Mint. Run openshield key on the server. It prints the metrics API URL and a fresh API key.
  2. Store. Paste both values into the Add server form in the console. The console stores the key server-side and never shows it again — dashboard pages only receive proxied, permission-checked responses.
  3. Rotate. Rerun openshield key on the server to issue a fresh key, then remove the server in the console and add it again with the new key. The console does not edit keys in place — remove and re-add is the supported flow.

When the console calls your agent, a 401 response means the key is wrong and a 403 means the caller IP is not in metrics.whitelist.

What a leaked key exposes

An osk_ key is read-only: whoever holds it can query GET /metrics and GET /health on that one agent, and only from an address allowed by metrics.whitelist. It cannot change the agent's config, control mitigation, or touch your account.

If a key leaks anyway, revoke it by rotating immediately: rerun openshield key on the server to issue a fresh key, then re-add the server in the console.

Next steps