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

# Agent setup

> Let your AI assistant create its own API key in under 30 seconds.

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

<Steps>
  <Step title="Request a verification code">
    The agent sends your email to the API:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the code">
    Paste the code when the agent asks for it:

    ```bash theme={null}
    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):

    ```json theme={null}
    {
      "data": {
        "token": "owt_...",
        "expires_at": "2026-04-16T12:15:00Z"
      }
    }
    ```
  </Step>

  <Step title="Create an API key">
    The agent uses the session token to create a permanent key:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Step>
</Steps>

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](/integrations/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