> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forecastable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scopes
> Integration API and MCP permission scopes for Forecastable.
Scopes control what an API key or OAuth token can read or write. Forecastable checks scopes on every authenticated Integration API request and MCP tool call.
Assign the narrowest scopes required for your integration. Both [API keys](/developers/api-keys) and [OAuth apps](/developers/oauth) are configured with an allowed scope list; requests cannot exceed that list.
## Approved scopes
| Scope | Access |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `organizations:read` | List organizations, read organization details, list organization users, set the active organization in MCP sessions |
| `accounts:read` | List and read accounts |
| `accounts:write` | Create, update, patch, and bulk-create accounts |
| `accounts:delete` | Archive accounts and leads |
| `contacts:read` | List and read contacts on accounts |
| `contacts:write` | Create, update, and patch contacts |
| `contacts:delete` | Archive contacts |
| `opportunities:read` | List and read opportunities |
| `opportunities:write` | Create, update, and patch opportunities |
| `opportunities:delete` | Delete or archive opportunities |
| `engage:read` | Read engagement configuration and activity |
| `engage:write` | Create and update engagement resources |
| `engage:send` | Send approved engagement messages |
| `feed:read` | Read account inbox (email, Slack, calendar) and dashboard communication feed / needs-attention. Dashboard endpoints require a user-backed token. |
| `plans:read` | Read account plans |
| `plans:write` | Create and update account plans, milestones, goals, and tasks |
| `plans:delete` | Archive account plans, milestones, goals, and tasks |
| `calendar:read` | View synced calendar events for the authenticated user (and authorized teammates for admin/consulting users). Requires a user-backed token. |
| `calendar:write` | Update synced calendar events owned by the authenticated user (title, time, participants, etc.). Requires a user-backed token. |
## Scope groups
Scopes follow a `resource:action` pattern:
* **`:read`** — list and get operations
* **`:write`** — create and update operations
* **`:delete`** — archive and delete operations
* **`engage:send`** — send messages (separate from engage read/write configuration)
`organizations:read` is required for most workflows because it lets clients discover which organizations a principal can access.
## Common combinations
### Read-only CRM assistant
```
organizations:read
accounts:read
contacts:read
opportunities:read
```
### CRM sync with writes
Add write scopes only for record types the integration should modify:
```
organizations:read
accounts:read
accounts:write
contacts:read
contacts:write
opportunities:read
opportunities:write
```
### Engagement automation
```
organizations:read
engage:read
engage:write
engage:send
```
## MCP tools by scope
The [MCP server](/developers/mcp) currently exposes tools for organizations, accounts, contacts, and opportunities.
| MCP tool | Required scope |
| ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `getMeta` | none |
| `listOrganizations`, `setActiveOrganization`, `getOrganization`, `listOrganizationUsers` | `organizations:read` |
| `listAccounts`, `getAccount` | `accounts:read` |
| `createAccount`, `updateAccount`, `deleteAccount`, `bulkCreateAccounts` | `accounts:write` / `accounts:delete` |
| `listAccountContacts`, `getContact` | `contacts:read` |
| `createAccountContact`, `updateContact`, `deleteContact` | `contacts:write` / `contacts:delete` |
| `listOpportunities`, `getOpportunity` | `opportunities:read` |
| `createOpportunity`, `updateOpportunity`, `deleteOpportunity` | `opportunities:write` / `opportunities:delete` |
| `listCalendarEvents`, `getCalendarEvent`, `getCalendarEventSummary`, `getCalendarEventActionItems`, `getCalendarEventTranscript` | `calendar:read` |
| `updateCalendarEvent` | `calendar:write` |
| `getAccountInbox`, `getAccountInboxThreadMessages`, `getAccountInboxSlackThread`, `getCommunicationAnalytics`, `listNeedsAttention` | `feed:read` |
Additional REST endpoints may be exposed as MCP tools over time.
## Organization context
Scopes control *what* a token can do. Organization context controls *where* it applies.
Most endpoints and MCP tools require an active organization in addition to the correct scope. Provide it with:
* header `X-Organization-Id`
* MCP tool input `headers.xOrganizationId`
* MCP session `setActiveOrganization` after `listOrganizations`
## Errors
| Error | Cause |
| ------------------ | ---------------------------------------------------------------------- |
| `403 forbidden` | Token is valid but missing the scope required for the endpoint or tool |
| `401 unauthorized` | Missing, expired, or revoked token |
When configuring keys or OAuth apps, the Forecastable developer settings UI shows the same scope descriptions listed in the table above.
## Live scope list
`GET /api/v1/meta` returns the current approved scope list, pagination defaults, and rate-limit configuration. This endpoint does not require authentication.
```bash theme={null}
curl -s https://app.forecastable.com/api/v1/meta | jq '.scopes'
```
## Related guides
Issue static tokens with a chosen scope set.
Let users approve a scoped set of permissions for third-party clients.
Per-token limits, 429 responses, and retry behavior.