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

# Workspace API keys

> Reach your team's shared notes and folders from the API using a workspace key.

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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Create the key">
    Click **New key**, give it a name, and tick the permissions it needs.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

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

```bash theme={null}
curl -H "Authorization: Bearer ow_wks_live_YOUR_KEY" \
  https://api.openwhispr.com/api/v1/spaces/list
```

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

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