Keys and Scopes
Where a credential comes from, how it travels on the wire, and the authority each call has to carry.
Keys and Scopes Documentation
One credential covers the whole plane. What it may do is decided by the scopes carried on it.
The credential
| Form | Sent as | Can do |
|---|---|---|
Account key, whisper_live_... | X-API-Key: <your key> | Everything its scopes allow. |
Read-only token, et_... | Authorization: Bearer et_... | Reads. It cannot change anything. |
The hosted MCP server takes the same account key as Authorization: Bearer. Treat every key as a password: keep it out of URLs, out of page source and out of a repository.
Getting a key
Sign in at console.whisper.security and create one. With no browser in the loop, two calls do the same thing: the first asks for a code by email, the second exchanges the code for the key.
curl -s https://console.whisper.security/api/signup \
-H 'content-type: application/json' \
-d '{"email": "you@example.com"}'
curl -s https://console.whisper.security/api/signup/verify \
-H 'content-type: application/json' \
-d '{"signup_id": "<from the first call>", "code": "<from the email>"}'
Keys a call hands back
register mints a second key, belonging to the agent it just created, and returns it on that one answer. The same answer carries a doh_url with a token inside it. Capture both at the moment of the call, and treat the doh_url as a password, because the token in the path is the credential.
Scopes
Each operation needs one scope on the key.
| Operation | Scope |
|---|---|
register, revoke, domain | admin:dns |
identity | dns:identity |
list, agent | dns:zone:read |
connect, token | dns:connect |
policy | dns:policy:write |
logs | dns:logs:read |
firewall | dns:firewall:write |
respond | dns:respond:write |
A policy call that also carries the whale key needs dns:whale:write beside dns:policy:write.
The DNS scopes over your own account are enrolled on the key the first time you use them, so a key made in the console can call register and policy with no further setup. Two are never enrolled that way and have to be granted: dns:respond:write and dns:whale:write.
A call whose key lacks the scope comes back 403 FORBIDDEN_SCOPE.
Calling with no key
The endpoint answers graph reads with no credential at all. Anything that writes needs one, and an unauthenticated write comes back 403 ANONYMOUS_WRITE. A credential issued to a resolve-only device reads and resolves but changes nothing, and answers 403 DEVICE_RESOLVE_ONLY.
The verification, registry and log paths in Keyless endpoints never take a credential, which is what lets a stranger check an identity you minted.