API Key Permissions

Create a key in Mosaic 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:

["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.

{
  "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.

Overview

Motion

Agents

Avatar Profiles

Agent Runs

Pipeline Observability

Automations

Node Types

Agent Nodes

Triggers

Webhooks

Asset Management

Credits

Plan

Social

Shared Stores

Restricted mode

Entity scopes

Give a dashboard agent read-only access

Handle permission errors

​Restricted mode

​Entity scopes

​Give a dashboard agent read-only access

​Handle permission errors

Restricted mode

Entity scopes

Give a dashboard agent read-only access

Handle permission errors