API keys and scopes
fleet:read, fleet:run, fleet:admin; what a key can and cannot do; rotation.
Creating a key
Settings → API keys (members make their own, up to fleet:run; admins and owners any, and see and revoke every key): give the key a name ("Claude Code on my laptop") and an access level. The key is shown once, looks like shc_…, and is stored as a peppered HMAC-SHA256 hash: nobody, including the Skillhook team, can read it back. Keys can carry an expiry date; past it, a key is refused exactly like a revoked one. Revoking a key takes effect immediately for anything that uses it. Each key belongs to the organisation it was created in and acts only there. It records who made it and carries their access to what is shared with them (never above its scope, and narrowed if their role drops); it keeps working if they leave, for what the whole organisation sees, until an admin revokes it.
skillhook makes its own: skillhook cloud login (skillhook 0.10 and newer) opens /activate in your browser, where a member, admin or owner approves it for an organisation (the page asks which, when you are in several) and an access level up to their role, and the new key goes straight to that terminal (below). It is listed here like any other, named after the computer, and revoked the same way.
The three scopes
A key has one scope, and each scope maps onto an organisation role: the key may do exactly what a person with that role may do, decided by the same tables (see Teams and roles and the command table under Machines and pairing). No scope acts as owner. The machine's own mode and policy apply to a key as they do to a person: a key cannot act on a machine paired in observe mode.
What keys never do
Whatever its scope, a key never manages access: it cannot create or revoke API keys, invite or remove people, change roles, pair a machine, or add a notification channel. Those are done by a signed-in person on the dashboard, so nothing a key does outlives it: a leaked key can neither widen nor outlive its access, and revoking it ends what it could do. A key can read the team and the channels and test a channel. One more thing stays out of its reach by design: a skill's secret. skillhook cloud secret has the machine generate it sealed to a key pair made for that one request, and the cloud only forwards the sealed value, so a model behind the hosted MCP server could never open it.
The Authorization header
Send the key as a bearer token on every request to /api/v1 and /api/mcp, never in a URL or a query string. Errors are RFC 9457 problems with a code and a request_id; see the error contract.
401 unauthorized: no bearer token in the header;401 invalid_key: the key is unknown, revoked or expired.403 forbidden: the operation needs a wider scope; the message names it.429 rate_limited: more than 600 requests a minute from this key, on the REST API and the hosted MCP server together;Retry-Aftersays when.503 unavailable: our trouble, worth a retry; never a 401 or a 404 when we could not look the key up.
Rotation
- Create a new key with the same scope.
- Put it where the old one was: the secret in CI, the header in each MCP client. On a computer that uses the CLI or the plugin,
skillhook cloud login --url https://skillhook.devagain makes a new key of its own when you approve it (with--keyit takes the one you made instead). - Revoke the old key. Anything still using it gets
401 invalid_keyat once.
The audit log records who created and revoked each key, by name, so a key can be traced without ever being shown.
Where the CLI keeps it
skillhook cloud login signs in with the browser, as RFC 8628 describes for devices: it shows a code and opens /activate with it, where you sign in, check that the page shows the same code, choose the organisation and the access, and approve. Members, admins and owners can, each up to their role (a member's key is capped at Run); viewers make no keys. The terminal asks every few seconds, and its first request after the approval gets a new key, made at that moment and handed over once: it never rests anywhere on our side, not even encrypted, and a sign-in nobody collects within ten minutes leaves no key behind. With --key it asks for a key you made at the terminal instead, without echoing it (or reads it from stdin with --key -). Either way it checks the key against the cloud (GET /api/v1/me) and keeps it in ~/.skillhook/.env as SKILLHOOK_CLOUD_API_KEY next to SKILLHOOK_CLOUD_API_URL, the cloud it belongs to. It is never printed again and never reaches a skill's run, even when a skill lists it in env:; the machine's own pairing token is a different credential and is never used for the API. skillhook cloud status says whether a key is kept and for which cloud; skillhook cloud logout forgets it. The local MCP server refuses to set or move these values, so an agent never handles the key.
In CI and scripts
The same two variables in the environment do what login does, without touching a file: set SKILLHOOK_CLOUD_API_KEY and SKILLHOOK_CLOUD_API_URL and every skillhook cloud command works. Store the key as a secret of your CI system and give it the narrowest scope the job needs.