# Permissions

Every permission a Block can declare, generated from the SDK.

## Permission families
Every manifest declares `permissions` with these families. Anything not declared is unavailable; declaring a permission never grants access the user has not authorized.

| Family | Allowed values |
| --- | --- |
| project | Project scopes below (any runtime) |
| capabilities | Exactly one hosted operation for `runtime: "capability"` (`text.generate`, `audio.speech`, `audio.transcribe`, `audio.music`, `audio.sfx`, `image.generate`, `video.generate`, `image.describe`, `media.analyze`, `web.fetch`, `web.research`, `timeline.propose`, `workspace.propose`, `connection.execute`), or `comfyui.execute` for `runtime: "comfyui"`. See [runtime capabilities](/docs/reference/capabilities). |
| actions | Portable media actions below, for `runtime: "javascript"` or `"module"` |
| desktop | Desktop permissions below, used through the host desktop bridge |
| network | For `runtime: "module"`: up to 8 exact https origins the Block calls with `stillmade.net.fetch`, each optionally with the key it needs (`{origin, auth: {scheme: "bearer" \| "header" \| "query" \| "oauth2", name or app, label, help}}`). People add their own key or sign in once per Block; the host adds it on its servers. Other runtimes: empty. See [Outside APIs](/docs/build/outside-apis). |
| connections | For `runtime: "module"`: up to 8 published adapters by app ID (`app:openapi:notion`), called with `stillmade.connections.call`. Other runtimes: empty. |
| filesystem, secrets | Must be empty arrays. Blocks have no ambient file or secret access; keys come from the people running the Block, through declared network access. |

## Project scopes
| Scope | Grants |
| --- | --- |
| `context.script.read` | Read the project's script as `script` through a declared `context` input. |
| `context.transcript.read` | Read the project's transcript as `transcript` through a declared `context` input. |
| `context.shots.read` | Read the project's shots as `shot[]` through a declared `context` input. |
| `context.shotPlan.read` | Read the project's shotPlan as `shot-plan` through a declared `context` input. |
| `context.scenes.read` | Read the project's scenes as `scene[]` through a declared `context` input. |
| `context.characters.read` | Read the project's characters as `character[]` through a declared `context` input. |
| `context.locations.read` | Read the project's locations as `location[]` through a declared `context` input. |
| `context.styles.read` | Read the project's styles as `style[]` through a declared `context` input. |
| `context.assets.read` | Read the project's assets as `asset[]` through a declared `context` input. |
| `context.files.read` | Read the project's files as `file[]` through a declared `context` input. |
| `context.generations.read` | Read the project's generations as `metadata[]` through a declared `context` input. |
| `context.versions.read` | Read the project's versions as `metadata[]` through a declared `context` input. |
| `context.timeline.read` | Read the project's timeline as `timeline` through a declared `context` input. |
| `context.editor.read` | Read the project's editor as `timeline` through a declared `context` input. |
| `context.canvas.read` | Read the project's canvas as `pipeline` through a declared `context` input. |
| `context.blueprint.read` | Read the project's blueprint as `bible` through a declared `context` input. |
| `context.panels.read` | Read the project's panels as `panel-document` through a declared `context` input. |
| `context.board.read` | Read the project's board as `board-document` through a declared `context` input. |
| `context.animation.read` | Read the project's animation as `scene-document` through a declared `context` input. |
| `context.metadata.read` | Read the project's metadata as `metadata` through a declared `context` input. |
| `asset.read` | Read authorized media references the host supplies through inputs or declared context; declaring it is not permission to any particular asset. |
| `asset.create` | Module Blocks: add a saved image, video or audio file to the project's media as a new asset with `stillmade.assets.create`. Needs edit access to the project. |
| `asset.version.append` | Module Blocks: add a saved file as the newest version of a project asset the Block received, read or created, keeping its history, with `stillmade.assets.appendVersion`. |
| `project.read` | Module Blocks: read the project while running with `stillmade.project.read(fields)`, limited to the metadata and each field declared with `context.FIELD.read`. |
| `project.patch` | Reserved. Accepted by the manifest validator; no host applies changes through it today. Use a `workspace.FIELD.propose` or `timeline.propose` proposal. |
| `timeline.read` | Reserved. Accepted by the manifest validator; read the Editor timeline with `context.timeline.read`. |
| `timeline.propose` | Propose a strict timeline edit (`timeline-edit` output). Requires `context.timeline.read`; the user previews and applies it. |
| `workspace.animation.propose` | Propose a `workspace-edit` to the animation workspace. Requires the matching `context.animation.read`; the user previews and applies it. |
| `workspace.canvas.propose` | Propose a `workspace-edit` to the canvas workspace. Requires the matching `context.canvas.read`; the user previews and applies it. |
| `workspace.blueprint.propose` | Propose a `workspace-edit` to the blueprint workspace. Requires the matching `context.blueprint.read`; the user previews and applies it. |
| `workspace.shotPlan.propose` | Propose a `workspace-edit` to the shotPlan workspace. Requires the matching `context.shotPlan.read`; the user previews and applies it. |
| `workspace.panels.propose` | Propose a `workspace-edit` to the panels workspace. Requires the matching `context.panels.read`; the user previews and applies it. |
| `workspace.board.propose` | Propose a `workspace-edit` to the board workspace. Requires the matching `context.board.read`; the user previews and applies it. |
| `workspace.editor.propose` | Propose a `workspace-edit` to the editor workspace. Requires the matching `context.editor.read`; the user previews and applies it. |
| `state.step` | Keep persistent per-Step state for a JavaScript Block that declares `manifest.state`. |
| `work.shared` | Run shared background work (`sharedWork`) that every collaborator in the project sees. |

## Portable media actions
A JavaScript Block returns a `{schemaVersion: 1, kind: "stillmade.media-action", operation, request, resultPort}` value for an action it declared; the host validates and performs it.

| Action | Performs |
| --- | --- |
| `final.render` | Ask the host to render the project timeline to a final video. |
| `stock.search` | Search approved stock photos, videos or audio by query. |
| `presenter.generate` | Generate presenter poses for a board from a prompt and its voiceover. |
| `quality.analyze` | Analyze up to 16 owned images for production quality. |
| `image.generate` | Generate one image from a bounded visual prompt through the host. |
| `image.generate.batch` | Generate up to 100 panel images from prompts in one aspect ratio, pinned to the requesting Block version. |
| `media.generate` | Generate up to 50 images, videos, voice recordings, music tracks or sound effects with any StillMade catalog model, voice and settings (aspect ratio, resolution, quality, duration, sound, seed, reference images, first and last frames, voice, speed, length), paid with the user's StillMade credits after they approve one maximum for the batch. |
| `youtube.upload` | Upload an owned video to the owner's connected YouTube channel with title, description, tags, visibility, schedule and disclosure fields. |

## Desktop permissions
| Permission | Allows |
| --- | --- |
| `screen.capture` | Choose a screen or window, then record it. |
| `cursor.track` | Global cursor coordinates and display geometry; no click or keyboard monitoring. |
| `camera.capture` | Camera recording after device and OS approval. |
| `microphone.capture` | Microphone recording after device and OS approval. |
| `clipboard.read` | Read clipboard text, bounded to 100,000 characters. |
| `clipboard.write` | Replace clipboard text. |
| `media.pick` | Native picker for up to 20 media files; no arbitrary path access. |
| `notifications.show` | A Block-branded desktop notification, at most one every ten seconds. |
| `power.keep-awake` | Keep the app from suspending until disabled, revoked, closed or expired. |
| `native.tools` | Use one exact versioned adapter for an approved installed desktop application. |

Details and request shapes: [desktop capabilities](/docs/reference/desktop-capabilities).