Reference
Authentication
Creating API keys, scopes, and how a key decides what you can read
Every request needs an API key in the X-API-Key header:
curl https://developers.caven.io/public/v1/recordings \
-H "X-API-Key: sk_your_key_here"Keys start with sk_, followed by 64 hexadecimal characters. Authorization: Bearer is not accepted. A request without an X-API-Key header is rejected with 401 API_KEY_REQUIRED.
Creating a key
API keys are managed by organization admins.
- In the web app, open Settings → API Keys and click New Key.
- Choose Personal or Organization (see below). This choice sits at the top of the form and only appears when you belong to an organization.
- Enter a Key Name (for example "CRM sync") so you can recognize it later.
- Optionally set an Expiry date. Leave it empty for a key that never expires.
- Pick the Scopes the key needs. The defaults cover all text data. For an on-prem connector, click On-prem connector to select exactly the twelve scopes a connector needs.
- Confirm your identity. If you have two-factor authentication turned on, enter your authenticator code. Otherwise Caven emails you a 6-digit code, valid for 10 minutes.
- Copy the key.
The key is shown once
Caven stores only a hash of the key, so it can't show it to you again. If you lose it, delete it and create a new one.
Personal and organization keys
| Personal key | Organization key | |
|---|---|---|
| Who can create one | Organization admins, for themselves | Organization admins |
| Recordings | Only recordings you made | Your own recordings and those in the spaces you can open in Caven. With recordings:organization-wide: every recording made by a member of the organization, including people who have since left |
| Action items, speakers, tags | Your own | The organization's |
/organization/... | The organization you belong to | The key's organization |
| Narrow to one member | No | Yes, with ?userId= |
Narrowing an organization key to one member
On any recording, action item, speaker or tag list, an organization key accepts ?userId= to return only that member's data:
curl "https://developers.caven.io/public/v1/recordings?userId=cmjal5xyj0000vaz4po9spv16" \
-H "X-API-Key: sk_your_org_key"A user ID from outside your organization returns an empty list. Get member IDs from /organization/users.
Spaces stay confidential
An organization key reads what its creator can open in Caven: their own recordings and the recordings in the spaces they are a member of. A space they are not in, or are excluded from, stays closed to the key, the same as in the app. To read every member's recordings, grant the recordings:organization-wide scope when you create the key. An on-prem connector key reaches the organization's recordings while Docker on-prem delivery is on.
Scopes
A scope grants access to a group of endpoints. A request to an endpoint the key has no scope for fails with 403 INSUFFICIENT_SCOPE.
| Scope | Grants | Default |
|---|---|---|
recordings:list | GET /recordings | Yes |
recordings:get | GET /recordings/:id | Yes |
transcripts:list | Transcripts and notes | Yes |
summaries:list | AI summaries | Yes |
action-items:list | Action items | Yes |
speakers:list | Speaker profiles | Yes |
tags:list | Tags | Yes |
organization:read | Organization, members, teams, folders | Yes |
media:list | List a recording's stored media files | No |
media:download | Download stored media (encrypted) | No |
media:key | Retrieve media decryption keys | No |
connector:register | Register an on-prem connector | No |
recordings:organization-wide | Organization keys only: read every member's recordings, including spaces the key's creator is not a member of | No |
The four media and connector scopes are never part of Select all or the defaults. They let a caller download recordings and obtain the keys to decrypt them, so you must grant them on purpose, one by one or with the On-prem connector button. See On-prem connector.
Older scope names
Keys created with earlier scope names keep working. recordings:read covers recordings:list and recordings:get, transcripts:read covers transcripts:list, summaries:read covers summaries:list, and recordings:transcript, recordings:summary, recordings:action-items and recordings:speakers cover the matching :list scope. None of the older names grant the media or connector scopes.
Older keys without scopes
Keys created before scopes existed have an empty scope list. Those keys can reach every endpoint except the media and connector ones. Create a new key if you want to limit access.
Managing keys
Under Settings → API Keys you can:
- Deactivate a key. It stops working immediately with
401 API_KEY_INVALID, and you can turn it back on later. - Delete a key. This is permanent.
- See when each key was last used, plus a log of recent requests (method, path, status and duration).
An expired key returns 401 API_KEY_EXPIRED.
Authentication errors
| Status | code | Meaning |
|---|---|---|
| 401 | API_KEY_REQUIRED | No X-API-Key header |
| 401 | API_KEY_INVALID | Unknown, deleted or deactivated key |
| 401 | API_KEY_EXPIRED | The key's expiry date has passed |
| 403 | INSUFFICIENT_SCOPE | The key exists but lacks the scope for this endpoint |
| 500 | AUTH_ERROR | The key could not be checked because of a server error. Retry later |