> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Permissions

> Give an agent only the API permissions it needs, and handle scope errors explicitly.

Create a key in [Mosaic](https://edit.mosaic.so) under API key settings. Only an organization owner or admin can create keys. Keys authenticate with `Authorization: Bearer mk_your_api_key` and apply across the organization's workspaces. `X-Workspace-Id` narrows a request; it does not grant access to a different organization.

## Restricted mode

Restricted mode is off by default, granting full access. Enable it to reveal a **None / Read / Write** control for each entity:

| Access level | Granted scopes | Behavior |
| - | - | - |
| None | Neither scope | Deny reads and writes for this entity. |
| Read | `entity:read` | Allow the entity's documented read operations. |
| Write | `entity:read`, `entity:write` | Allow read and write operations. |

The UI's Write level grants both explicit scopes. At the API enforcement layer, `entity:write` alone does not imply `entity:read`. Existing keys retain full access. A key's `scopes: null` means full access; an empty list means no entity permissions. The editor requires at least one permission when creating a restricted key.

## Entity scopes

| Entity | Read scope | Write scope | Read allows | Write allows |
| - | - | - | - | - |
| Agents | `agents:read` | `agents:write` | Workflow graphs, tiles, and metadata | Create, update, duplicate, delete, and share workflows |
| Agent runs | `agent_runs:read` | `agent_runs:write` | Run status, progress, tasks, outputs, and notification receipts | Start, resume, or cancel runs |
| Triggers | `triggers:read` | `triggers:write` | Trigger configuration, watched folders, storage events, and batches | Change trigger configuration |
| Uploads | `uploads:read` | `uploads:write` | Get viewing URLs for existing video, image, or audio files | Create upload URLs and finalize uploads |
| Billing | `billing:read` | `billing:write` | Credits, usage, and plan information | Change billing settings or plans |
| Social | `social:read` | `social:write` | Connections, posts, comments, and analytics | Connect accounts, publish, edit, or delete posts |
| Streaming | `streaming:read` | `streaming:write` | Livestream status, connections, ingestion health, and viewers | Create, recover, start, end, or delete livestreams and manage connections |
| Avatar profiles | `avatar_profiles:read` | `avatar_profiles:write` | Avatar profiles | Create avatar profiles |
| Shared stores | `shared_stores:read` | `shared_stores:write` | Stores and entries | Create, update, or delete stores and entries |
| Automations | `automations:read` | `automations:write` | Automation reads outside the run/batch endpoints | Automation writes |

Scopes grant permission to call an API surface; they do not enable a feature or bypass plan, organization, workspace, or product availability checks. Streaming is currently limited to enabled organizations. `/automations/runs` requires `agent_runs:read`; `/automations/ingest-batches` requires `triggers:read`.

## Give a dashboard agent read-only access

Enable Restricted mode. Set **Agents**, **Agent runs**, and **Triggers** to **Read**, and leave other entities at **None**. The resulting scopes are:

```json theme={null}
["agents:read", "agent_runs:read", "triggers:read"]
```

This key can inspect a pipeline and its delivery receipts. It cannot execute or cancel runs, modify workflows, upload files, or publish posts.

`GET /whoami` verifies a valid key and returns its `scopes` even if the key has no entity permissions. It does not grant access to other endpoints. Keys cannot elevate their own permissions; ask an organization owner or admin for a replacement key when an integration needs additional access.

## Handle permission errors

A missing scope returns HTTP **403** with a stable `code`, `required_scope`, and the current `granted_scopes`. `retryable: false` means the agent must stop retrying this operation with the same key.

```json theme={null}
{
  "detail": "This API key cannot POST /agent/11111111-1111-4111-8111-111111111111/run. Required scope: agent_runs:write.",
  "code": "api_key_scope_required",
  "required_scope": "agent_runs:write",
  "granted_scopes": [
    "agents:read",
    "agent_runs:read",
    "triggers:read"
  ],
  "retryable": false,
  "request": {
    "method": "POST",
    "path": "/agent/11111111-1111-4111-8111-111111111111/run"
  },
  "resolution": "Ask an organization owner or admin to create an API key granting agent_runs:write. Retrying with this key will not grant access.",
  "documentation_url": "https://docs.mosaic.so/api/api-key-scopes"
}
```

For `api_key_scope_required`, explain the missing scope to the user and request an owner/admin-issued key with that permission. Do not silently request full access or attempt another endpoint to bypass the restriction.

For `api_key_scope_unsupported`, `required_scope` is null: the requested endpoint is not classified for restricted keys. Use a documented endpoint or contact Mosaic support. This is not a scope name to grant.

Other authorization failures, such as paid-plan requirements or a conflicting workspace, also return 403 with `detail`; do not assume every 403 is a scope denial. Invalid or revoked keys return 401.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.