Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openwhispr.com/llms.txt

Use this file to discover all available pages before exploring further.

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

1

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.
2

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"
  }
}
3

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:
EndpointMethodDescription
/v1/keys/createPOSTCreate a new API key
/v1/keys/listGETList active API keys
/v1/keys/{id}/revokePOSTRevoke 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