Workspace API keys

A personal API key reaches your own notes. A workspace key reaches the notes and folders inside your team spaces, so an integration can read or write shared content without being tied to one person’s account. Workspace keys start with ow_wks_live_ instead of owk_live_.

Create a workspace key

Only a workspace owner or admin can create one.

Open the Developer tab

In the desktop app, go to Settings > Account > Workspace and pick the Developer tab.If you don’t see the tab, your role in the workspace is member — ask an owner or admin.

Create the key

Click New key, give it a name, and tick the permissions it needs.

Copy it now

The key is shown once. Copy it before closing the dialog — you can’t see it again, only revoke it and make a new one.

A workspace can have up to 20 active keys at a time.

Scopes

Workspace scopes are separate from personal ones, and they only ever apply to team-space content.

Scope	Access
`workspace:notes:read`	List, get, and search notes in a space. Read note transcripts.
`workspace:notes:write`	Create, update, and delete notes in a space.
`workspace:folders:read`	List folders in a space.
`workspace:folders:write`	Create folders in a space.
`workspace:*`	Everything above.

Any one of the four notes/folders scopes also lets the key list the spaces it can see.

The key-creation dialog offers a few more permissions than the ones listed here. Those cover areas the API doesn’t expose yet, so a key holding only those can’t call anything — stick to the scopes above.

Naming a space

Endpoints that work across a collection need to know which space you mean. Pass the space’s id as space_id — a query parameter on the list endpoints, a body field on the create ones:

Endpoint	`space_id`
`GET /notes/list`	Required
`POST /notes/search`	Required
`POST /notes/create`	Required
`GET /folders/list`	Required
`POST /folders/create`	Required
`GET /notes/{id}` · `PATCH` · `DELETE`	Not used — the note id identifies it
`GET /notes/{id}/transcript`	Not used
`GET /spaces/list`	Not used

Two rules the API enforces on the endpoints that take it:

A workspace key without space_id gets 400 validation_error — “space_id is required for workspace API keys”.
A personal key with space_id gets the same status. A personal key can’t reach team-space content, and silently ignoring the parameter would hide that.

List the spaces a key can see

curl -H "Authorization: Bearer ow_wks_live_YOUR_KEY" \
  https://api.openwhispr.com/api/v1/spaces/list

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Engineering",
      "slug": "engineering",
      "description": "Team notes",
      "emoji": "🛠",
      "created_at": "2026-07-14T09:12:00.000Z",
      "updated_at": "2026-07-28T16:04:00.000Z"
    }
  ]
}

Archived spaces are left out. Take an id from here and pass it as space_id.

Read notes from a space

curl -H "Authorization: Bearer ow_wks_live_YOUR_KEY" \
  "https://api.openwhispr.com/api/v1/notes/list?space_id=550e8400-e29b-41d4-a716-446655440000&limit=20"

Responses, pagination, and errors work exactly as they do for personal keys — see the API overview.

What workspace keys don’t do

The CLI doesn’t use them. It works against your own notes — use a personal key.
The MCP server doesn’t use them either, for the same reason.
They can’t reach private notes, including your own. A workspace key sees team-space content and nothing else.

Security

Only the SHA-256 hash is stored, so a lost key can’t be recovered — revoke it and create another.
Naming a space that isn’t in the key’s workspace returns 404 not_found rather than a permission error, so a key can’t be used to discover which spaces exist elsewhere.
Revoking a key stops it working immediately, and any integration using it starts failing at once.

Overview

CLI

Integrations

Open source

Create a workspace key

Scopes

Naming a space

List the spaces a key can see

Read notes from a space

What workspace keys don’t do

Security

​Create a workspace key

​Scopes

​Naming a space

​List the spaces a key can see

​Read notes from a space

​What workspace keys don’t do

​Security

Create a workspace key

Scopes

Naming a space

List the spaces a key can see

Read notes from a space

What workspace keys don’t do

Security