Agent setup - OpenWhispr

AI assistants like Claude, Cursor, and VS Code can create their own OpenWhispr API key without opening the desktop app. The entire flow happens via API — the only human step is pasting a 6-digit code.

How it works

Request a verification code

The agent sends your email to the API:

curl -X POST https://api.openwhispr.com/api/v1/auth/email-code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

You’ll receive a 6-digit code by email.

Verify the code

Paste the code when the agent asks for it:

curl -X POST https://api.openwhispr.com/api/v1/auth/email-code/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "482901"}'

Returns a short-lived session token (valid for 15 minutes):

{
  "data": {
    "token": "owt_...",
    "expires_at": "2026-04-16T12:15:00Z"
  }
}

Create an API key

The agent uses the session token to create a permanent key:

curl -X POST https://api.openwhispr.com/api/v1/keys/create \
  -H "Authorization: Bearer owt_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Code - MacBook Pro", "scopes": ["notes:read", "notes:write"]}'

Returns:

{
  "data": {
    "key": "owk_live_...",
    "id": "...",
    "name": "Claude Code - MacBook Pro",
    "scopes": ["notes:read", "notes:write"],
    "expires_at": null,
    "created_at": "2026-04-16T12:00:00Z"
  }
}

The agent stores the owk_live_ key and uses it for all future requests — same as a key created in the desktop app.

Rate limits

1 code per 60 seconds per email
5 codes per hour per email
10 codes per hour per IP
5 attempts per code before it’s locked
Codes expire after 10 minutes
Session tokens expire after 15 minutes

Managing keys via the API

Once authenticated with a session token or desktop session, you can manage keys:

Endpoint	Method	Description
`/v1/keys/create`	POST	Create a new API key
`/v1/keys/list`	GET	List active API keys
`/v1/keys/{id}/revoke`	POST	Revoke an API key

See API keys for scope details and limits.

Security

The verification code is hashed server-side — it’s never stored in plain text
Session tokens have a 15-minute TTL and can only manage API keys (not read notes)
The token prefix owt_ distinguishes session tokens from owk_live_ API keys
Requesting a code for a non-existent email returns the same response to prevent enumeration

​How it works

​Rate limits

​Managing keys via the API

​Security

How it works

Rate limits

Managing keys via the API

Security