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

# Scopes

> The permission scopes an Alterscope API key can hold, and which tier each scope requires.

Every API key carries a set of **scopes** — the operations it is permitted to perform. Scopes are assigned when a key is minted and enforced server-side on every request. A request whose key lacks the required scope returns `403` with an error `code` of `insufficient_scope` (see [Errors](/develop/get-started/errors)).

Most read scopes are available on every tier, including Free. A handful of advanced market-intelligence scopes (full regime history, flow forecasts, and live WebSocket deltas) require a higher [tier](/develop/get-started/rate-limits); those are marked in the **Tier** column below.

## Read scopes

| Scope               | Unlocks                                                  | Tier |
| ------------------- | -------------------------------------------------------- | ---- |
| `read:yield`        | Read yield opportunities, universe, timeseries           | All  |
| `read:yield:detail` | Read detailed opportunity data (risk factors, scenarios) | All  |
| `read:watchlist`    | Read your watchlist                                      | All  |
| `read:screens`      | Read saved screens                                       | All  |
| `read:alerts`       | Read alert rules and events                              | All  |
| `read:portfolio`    | Run portfolio analytics                                  | All  |

## Market-intelligence scopes

| Scope                     | Unlocks                                             | Tier       |
| ------------------------- | --------------------------------------------------- | ---------- |
| `read:regime`             | Read current market regime + last-7-day history     | Analyst+   |
| `read:regime:full`        | Read full regime history beyond the 7-day clamp     | Team+      |
| `read:regime:transitions` | Read the regime transition-probability matrix       | Team+      |
| `read:regime:ws`          | Subscribe to live regime WebSocket deltas           | Enterprise |
| `read:flows`              | Read current capital flows + last-7-day timeseries  | Analyst+   |
| `read:flows:forecast`     | Read GNN flow forecasts and full timeseries history | Team+      |
| `read:flows:ws`           | Subscribe to live capital-flow WebSocket deltas     | Enterprise |
| `read:detector`           | Read live detector findings                         | Analyst+   |

## Write scopes

| Scope             | Unlocks                                              |
| ----------------- | ---------------------------------------------------- |
| `write:watchlist` | Modify your watchlist                                |
| `write:screens`   | Create or modify screens                             |
| `write:alerts`    | Create or modify alert rules                         |
| `write:execution` | Prepare, continue, simulate, or execute transactions |
| `write:rebalance` | Simulate or execute portfolio rebalances             |
| `write:agents`    | Create or mutate agent tasks and sessions            |

## MCP scopes

These gate [Model Context Protocol](/develop/ai-and-mcp/mcp-server) tool invocation. `mcp:deploy:mainnet` is the highest-privilege scope.

| Scope                | Unlocks                                                             |
| -------------------- | ------------------------------------------------------------------- |
| `mcp:read`           | Call read-only MCP tools (graph queries, regime, risk scoring read) |
| `mcp:backtest`       | Call MCP `backtest_strategy` + `replay_cascade_event`               |
| `mcp:simulate`       | Call MCP `simulate_strategy`                                        |
| `mcp:deploy:testnet` | Call MCP `deploy_to_testnet`                                        |
| `mcp:deploy:mainnet` | Call MCP `promote_to_mainnet` (highest privilege)                   |
| `mcp:eval:write`     | Submit results to the MCP public eval leaderboard                   |

## Admin scopes

| Scope        | Unlocks                                       |
| ------------ | --------------------------------------------- |
| `admin:keys` | Mint and manage API keys for the organization |

<Note>
  Tier names (Free, Analyst, Team, Enterprise) follow the live plan definitions. If you hold an older key issued under a previous tier name, your entitlements are unchanged — what a key can do is governed by its scopes, not its tier label.
</Note>