Programmatic Signup (for Agents)

Two HTTP calls to a working Whisper API key. Built for AI agents and automated runtimes — no browser, no CAPTCHA, no human-in-the-loop. Email verification only.

On this page (10)

What you get
The two-call flow
1. Start the signup
2. Verify the code
3. Use the key
Node / TypeScript
Python
Error responses
Running without a key
See also

Whisper is designed for AI agents to discover, sign up for, and start using without a human in the loop. This page walks through the programmatic signup endpoint — two HTTP calls, email verification only, and you get a working API key against the full internet-infrastructure graph and the Whisper MCP server.

If you're a human looking for the regular signup form, head to console.whisper.security/sign-up instead.

What you get

Every signup — programmatic or browser-based — provisions:

An API key (whisper-…) valid against graph.whisper.security and mcp.whisper.security.
Access that does not expire. The signup asks for an email address and nothing else.
A console dashboard at console.whisper.security where the human owner of the email can see usage and manage keys.

Sign-up is deliberately lightweight: an email address and a one-time code, with no CAPTCHA to solve.

The two-call flow

bash

curl -s -X POST https://console.whisper.security/api/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-agent@example.com",
    "attribution": {
      "agent_name": "your-agent-name",
      "agent_runtime": "claude-desktop | cursor | langchain | openai-assistants | custom",
      "agent_version": "1.2.3",
      "source": "smithery | mcp-directory | self | blog-post"
    }
  }'

Response:

json

{ "signup_id": "...", "expires_at": "2026-05-16T18:00:00Z" }

Whisper emails a 6-digit verification code to the address you provided. The code expires in 15 minutes; you have 5 verification attempts before the signup is invalidated.

The attribution block is optional and never gating. We use it only for product telemetry — to know which agent runtimes are picking up Whisper so we can prioritize improvements that target your runtime. Set whatever values make sense; nothing is rejected.

2. Verify the code

bash

curl -s -X POST https://console.whisper.security/api/signup/verify \
  -H "Content-Type: application/json" \
  -d '{ "signup_id": "<from step 1>", "code": "<from email>" }'

Response:

json

{
  "user_id": "user_...",
  "api_key": "whisper-...",
  "plan": "free",
  "mcp_url": "https://mcp.whisper.security",
  "docs_url": "https://www.whisper.security/docs/ai/agent-signup",
  "dashboard_url": "https://console.whisper.security"
}

The returned api_key is immediately usable. No further setup required.

3. Use the key

Against the graph DB. The canonical header for the graph endpoint is X-API-Key; Authorization: Bearer <key> (and Authorization: ApiKey <key>) are also accepted if that fits your client better:

bash

curl -s https://graph.whisper.security/api/query \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (h:HOSTNAME {name: \"example.com\"})-[:RESOLVES_TO]->(ip) RETURN ip.name LIMIT 10"}'

Against the MCP server — drop this into your Claude Desktop / Cursor / VS Code MCP client config (MCP uses Authorization: Bearer):

json

{
  "mcpServers": {
    "whisper": {
      "url": "https://mcp.whisper.security",
      "headers": { "Authorization": "Bearer <your_api_key>" }
    }
  }
}

Node / TypeScript

typescript

const signup = await fetch('https://console.whisper.security/api/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'your-agent@example.com',
    attribution: { agent_name: 'my-agent', source: 'self' },
  }),
}).then((r) => r.json());

// ... fetch the code from your inbox ...

const { api_key } = await fetch('https://console.whisper.security/api/signup/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signup_id: signup.signup_id, code: process.env.CODE }),
}).then((r) => r.json());

const result = await fetch('https://graph.whisper.security/api/query', {
  method: 'POST',
  headers: {
    'X-API-Key': api_key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'MATCH (h:HOSTNAME {name: "example.com"})-[:RESOLVES_TO]->(ip) RETURN ip.name LIMIT 10',
  }),
}).then((r) => r.json());

Python

python

import os, requests

signup = requests.post(
    "https://console.whisper.security/api/signup",
    json={
        "email": "your-agent@example.com",
        "attribution": {"agent_name": "my-agent", "source": "self"},
    },
).json()

# ... fetch the code from your inbox ...

verified = requests.post(
    "https://console.whisper.security/api/signup/verify",
    json={"signup_id": signup["signup_id"], "code": os.environ["CODE"]},
).json()

api_key = verified["api_key"]

result = requests.post(
    "https://graph.whisper.security/api/query",
    headers={"X-API-Key": api_key},
    json={
        "query": 'MATCH (h:HOSTNAME {name: "example.com"})-[:RESOLVES_TO]->(ip) RETURN ip.name LIMIT 10'
    },
).json()

Error responses

400 captcha_missing_token — Bot protection is switched on for sign-ups at the moment. Contact support@whisper.security and we will complete the sign-up with you.
400 verification_failed — Wrong code. Response includes attempts_remaining. After 5 wrong attempts the signup is invalidated; re-call /api/signup for a fresh code.
404 on /api/signup/verify — Signup expired (15-min window) or already consumed. Re-call /api/signup.
429 on /api/signup/verify — Too many attempts; signup invalidated. Re-call /api/signup.

Running without a key

The graph endpoint at https://graph.whisper.security/api/query answers with no auth header at all, which is enough to try a single pivot before you sign up. Most of the cross-layer recipes in these docs need a key: if one comes back refused or empty, send the key from step 2 as X-API-Key and run it again.

Programmatic Signup (for Agents)