# Agent Keys

Agent keys authenticate MCP and HTTP API calls. They are scoped to one organization and can optionally be bound to one workspace.

## Create a key

Go to **Admin > Settings > API**.

1. Enter a key name that explains the automation, for example docs-agent or openapi-sync.
2. Choose a workspace. Pick one workspace for least privilege, or Whole organization when the agent must operate across workspaces.
3. Choose permissions. Use All permissions for a fully trusted automation, a group checkbox for one workflow area, or individual checkboxes for exact access.
4. Choose an expiry.
5. Create the key and copy the token immediately.

The plaintext token starts with cowl_pat_ and is shown once. After that, ContextOwl stores only the hash and display prefix.

## Scope model

- Organization: every request is tenant-scoped by the key owner.
- Workspace: a bound key can only read or write that workspace.
- Permissions: explicit capabilities such as article.read or workspace.create.
- Role ceiling: the owner's org role must also allow the action.
- Member scope: if the owner is restricted to assigned workspaces, the key inherits that restriction.

Workspace-bound keys may omit the workspace argument in MCP tools. Organization-wide keys must pass a workspace argument for workspace-scoped tools.

## Permission picker

The permission picker is grouped by workflow:

| Group | What it controls |
| --- | --- |
| Content | Search, read, create, update, and publish articles |
| Navigation | Create sections and place articles in the sidebar |
| Changelog | Read, create, update, publish, and delete changelog entries |
| Workspaces | List, create, update, and delete workspaces |
| OpenAPI | Attach, sync, detach, and arrange generated API reference docs |

Select All permissions only for trusted automations. For most agents, select one group and remove any permissions the agent does not need.

## Revoke access

Delete the key from **Admin > Settings > API**. Future requests using that token return 401.

## Rotation

Create a replacement key, deploy it to the client, confirm the client works, then revoke the old key. Existing keys show their prefix, permission count, expiry, and last-used timestamp so you can identify stale clients.