Scopes

# Scopes

import {Callout, Head} from "zudoku/components";

<Head>
  <title>Scopes | FlowGuard</title>
</Head>

Scopes limit what an access token can do in FlowGuard. Choose them when you create an [access token](/developers/authentication#access-tokens). Start with the narrowest scope that covers your integration. The shared [scopes guide](/developers/scopes) explains how parent scopes and write access work.

Each endpoint in the [REST API reference](/api/flowguard) lists its required scope under security.

## Available scopes

### Broad scopes

| Scope | Access |
|---|---|
| `flowguard` | Every user-facing FlowGuard API operation |
| `flowguard:read` | Every resource read operation |
| `flowguard:write` | Every resource write and read operation |

### Logs

| Scope | Access |
|---|---|
| `flowguard:logs:read` | Discover log fields and query request logs |

Both `GET /logs/fields` and `POST /logs/query` use this read scope. FlowGuard does not have a separate write scope for logs.

### Rules

| Scope | Access |
|---|---|
| `flowguard:rules:read` | List and retrieve rules, and inspect rule capabilities |
| `flowguard:rules:write` | Create, update, disable, and delete rules; also grants rule reads |

### Actions

| Scope | Access |
|---|---|
| `flowguard:actions:read` | List and retrieve actions |
| `flowguard:actions:write` | Create, update, and delete actions; also grants action reads |

### Servers and IP lists

| Scope | Access |
|---|---|
| `flowguard:servers:read` | List and retrieve FlowGuard proxies, configuration, status, and capabilities |
| `flowguard:servers:write` | Create, update, and delete FlowGuard proxies; also grants proxy reads |
| `flowguard:ip_lists:read` | Read team and global IP lists and their entries |
| `flowguard:ip_lists:write` | Create, update, and delete team IP lists and manage their entries; also grants IP-list reads |

<Callout type="info">
Scopes are hierarchical. A resource write scope includes the matching read scope. `flowguard:read` grants every resource read scope, `flowguard:write` grants every resource write and read scope, and `flowguard` grants everything. A resource scope does not grant access to unrelated resources.
</Callout>

## Example token configurations

### Query request logs

```text
flowguard:logs:read
```

The token can discover available log fields and query logs. It cannot read or change rules and actions.

### Build a rule editor

```text
flowguard:rules:write flowguard:actions:write flowguard:servers:read flowguard:ip_lists:read
```

The token can inspect rule capabilities, manage rules and actions, and read the servers and IP lists that rules can reference.

### Read everything

Use the broad read scope for reporting, monitoring, or inventory across FlowGuard.

```text
flowguard:read
```