Whisper Online Authentication

generated: '2026-09-19'
method: searched
source: https://whisper.online/docs/control-plane
derived_from: openapi/whisper-online-openapi.json
docs:
- https://whisper.online/docs/control-plane
- https://whisper.online/docs/graph-api
- https://whisper.online/docs/account-and-keys
- https://whisper.online/.well-known/agent-onboarding.json
- https://www.whisper.security/docs/ai/agent-signup
- https://www.whisper.security/docs/ai/mcp/setup
- https://www.whisper.security/docs/cypher-api/reference
- https://mcp.whisper.security/.well-known/oauth-authorization-server
summary:
  types: [apiKey, http-bearer, oauth2, network-identity]
  api_key_in: [header]
  keyless_tier: true
schemes:
- name: whisperApiKey
  type: apiKey
  in: header
  parameter: X-API-Key
  description: 'A whisper_live_... key (the openapi securityScheme). Obtainable from an email address alone with no human step: POST https://console.whisper.security/api/signup {email} then POST /api/signup/verify {signup_id, code} returns the key (6-digit code, 15-minute TTL, 5 tries). Required only for the control plane (CALL whisper.agents) and the one graph write (submit); every other read answers keyless. The secret is shown once at creation.'
  sources: [openapi/whisper-online-openapi.json, 'https://whisper.online/.well-known/agent-onboarding.json']
- name: bearer / ApiKey (graph endpoints)
  type: http
  scheme: bearer
  description: 'On graph.whisper.online / graph.whisper.security the same key is also accepted as Authorization: Bearer <key> or Authorization: ApiKey <key>; X-API-Key is canonical. A missing or unrecognised key does NOT fail the request — it runs with reduced (anonymous) access and answers 200; confirm with CALL whisper.quota() (isAnonymous must be false).'
  sources: ['https://www.whisper.security/docs/cypher-api/reference']
- name: OAuth 2.1 (hosted MCP server)
  type: oauth2
  flows:
    authorizationCode:
      authorizationUrl: https://mcp.whisper.security/oauth/authorize
      tokenUrl: https://mcp.whisper.security/oauth/token
      refreshUrl: https://mcp.whisper.security/oauth/token
      scopes: {mcp:read: the whole read-only surface, offline_access: refresh token, mcp:query: legacy alias of mcp:read}
  description: 'RFC 9728 protected resource; RFC 7591 dynamic client registration and Client ID Metadata Documents; PKCE S256 only; public clients (token_endpoint_auth_methods_supported [none]); access tokens 1 hour, refresh tokens up to 180 days rotating. Static keys are the fallback as Authorization: Bearer or X-API-Key; a request with no credentials is rejected with 401 (probed 2026-09-19). Detail in scopes/whisper-online-scopes.yml.'
  sources: ['https://www.whisper.security/docs/ai/mcp/setup', well-known/whisper-online-mcp-oauth-authorization-server.json]
- name: agent-plane address-as-credential
  type: network-identity
  description: 'From inside a connected agent, requests to https://[<agent /128>]/api/query and the per-verb GETs (/identify?q=, /assess, /explain ...) carry no key at all: the routable /128 the request originates from IS the credential, and the answer is scoped to that identity. Verifiers check the identity keylessly via reverse DNS + forward AAAA + DANE TLSA (3 1 1) under DNSSEC + RDAP.'
  sources: ['https://whisper.online/docs/graph-api', 'https://menu.whisper.online/menu']
- name: per-agent API key
  type: apiKey
  in: header
  parameter: X-API-Key
  description: 'CALL whisper.agents({op:''register''}) mints a brand-new agent with its own api_key, "handed back exactly once". op:identity allocates a /128 on the caller''s existing key instead.'
  sources: ['https://whisper.online/docs/control-plane']
cli_key_ladder: 'WHISPER_API_KEY or WHISPER_KEY env, else the credential saved by `whisper login` (browser device-flow at console.whisper.online, or a pasted key); the key travels only in the header, never in the query string or a Cypher literal.'
console: 'https://console.whisper.security (sign-up) / https://console.whisper.online (sign-in); the console issues short-lived session tokens for browser use; browser cross-origin calls to the API are refused with 403.'
mtls_dpop: 'A per-agent CA (Whisper Agent Identity Root CA / Issuing CA, O=viaGraph B.V.; fingerprints at /.well-known/whisper-ca.json), mTLS and DPoP are documented for agent-to-server authentication at /docs/per-agent-ca and /docs/egress-auth; not part of the REST API securitySchemes.'