Scopes

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 and OAuth apps 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 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.

curl -s https://app.forecastable.com/api/v1/meta | jq '.scopes'

API keys

Issue static tokens with a chosen scope set.

OAuth apps

Let users approve a scoped set of permissions for third-party clients.

Rate limits

Per-token limits, 429 responses, and retry behavior.

Getting Started

AI

Developers

Integrations

Approved scopes

Scope groups

Common combinations

Read-only CRM assistant

CRM sync with writes

Engagement automation

MCP tools by scope

Organization context

Errors

Live scope list

API keys

OAuth apps

Rate limits

​Approved scopes

​Scope groups

​Common combinations

​Read-only CRM assistant

​CRM sync with writes

​Engagement automation

​MCP tools by scope

​Organization context

​Errors

​Live scope list

​Related guides

API keys

OAuth apps

Rate limits

Approved scopes

Scope groups

Common combinations

Read-only CRM assistant

CRM sync with writes

Engagement automation

MCP tools by scope

Organization context

Errors

Live scope list

Related guides