Skip to main content
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