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

> ## Agent Instructions
> Flowy is a node-based AI creative platform: you generate images, video, audio, 3D and vector on an infinite Canvas, refine on the Studio timeline, and export or publish from the same project.
> Prefer the Flowy MCP server (https://mcp.tryflowy.ai/mcp) or the REST API at https://apis.tryflowy.ai/v1 for programmatic work. Install with `flowy mcp install` from the @flowy/cli package.
> Credits are workspace-scoped. Generations reserve credits on start and only deduct on success, so failed runs refund automatically.

# Permissions

> Scope an API key to exactly the operations it needs.

Every API key carries a set of **scopes** that decide which operations it can perform. Giving a key the narrowest scopes it needs limits the blast radius if it ever leaks. A read‑only key, for instance, can inspect flows and read run results but can never spend a credit.

## Scopes

| Scope        | Grants                                           |
| ------------ | ------------------------------------------------ |
| `apps:read`  | List flows and read a flow's input/output schema |
| `apps:write` | Create and publish a flow                        |
| `runs:read`  | Poll a run's status and outputs                  |
| `runs:write` | Start runs (spends credits)                      |

## Permission presets

When you create a key you pick a preset. Internally it resolves to the scopes above.

<CardGroup cols={3}>
  <Card title="Full">
    `apps:read` · `apps:write` · `runs:read` · `runs:write`

    Everything: discover flows, create/publish flows, start runs, and read results.
  </Card>

  <Card title="Read-only">
    `apps:read` · `runs:read`

    Inspect flows and read run results, but **cannot start runs**. A good default for keys that only poll.
  </Card>

  <Card title="Restricted">
    You choose

    Tick exactly the scopes the key should have.
  </Card>
</CardGroup>

## Which scope each endpoint needs

| Endpoint                     | Required scope |
| ---------------------------- | -------------- |
| `GET /v1/apps`               | `apps:read`    |
| `POST /v1/apps`              | `apps:write`   |
| `GET /v1/apps/{appId}`       | `apps:read`    |
| `POST /v1/apps/{appId}/runs` | `runs:write`   |
| `GET /v1/runs/{runId}`       | `runs:read`    |

A request to an endpoint whose scope the key doesn't hold returns `403`:

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{ "error": "this API key lacks the runs:write scope" }
```

<Tip>
  A common, safe setup for a browser **publishable** key is `apps:read` + `runs:write` + `runs:read` (so the page can fetch the flow's inputs, start a run, and show the result) combined with a tight domain allowlist and a daily spend cap.
</Tip>

## Editing a key's permissions

You can change a key's preset or scopes any time from **Settings → API keys → Edit**. The new permissions take effect immediately on the next request. A key's **type** (secret/publishable) and **owner** (you/machine), however, are fixed at creation.