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. User-backed OAuth and API-key requests are also limited by the user’s current organization role. A token cannot grant access the user does not have in that organization. Client-credential tokens stay token-scoped only.

Approved scopes

Scope	Access
`organizations:read`	List organizations and read organization details
`users:read`	List users in an organization
`accounts:read`	List and read accounts
`accounts:create`	Allow account creation; also requires `accounts:write`
`accounts:write`	Update accounts
`accounts:archive`	Archive accounts
`contacts:read`	List and read contacts
`contacts:write`	Create and update contacts
`contacts:archive`	Archive contacts
`opportunities:read`	List and read opportunities
`opportunities:write`	Create and update opportunities
`opportunities:archive`	Archive opportunities
`leads:read`	List and read leads
`leads:write`	Create and update leads
`leads:archive`	Archive leads
`relationship_maps:read`	Read relationship maps
`relationship_maps:write`	Create and update relationship maps
`plans:read`	Read partner plans
`plans:write`	Create and update partner plans
`plans:archive`	Archive partner plans
`plans.personal:read`	Read personal plans
`plans.personal:write`	Create and update personal plans
`plans.personal:archive`	Archive personal plans
`plan_items:read`	Read plan milestones, goals, and tasks
`plan_items:write`	Create and update plan milestones, goals, and tasks
`plan_items:archive`	Archive plan milestones, goals, and tasks
`feed:read`	Read dashboard aggregates and needs-attention
`inbox:read`	Read inbox threads and message bodies
`analytics:read`	Read communication analytics
`calendar:read`	View synced calendar events
`calendar:write`	Update synced calendar events
`calls:read`	Read call summaries
`transcripts:read`	Read call transcripts
`action_items:read`	Read call action items
`engage.templates:read` / `:write` / `:archive`	Engagement templates
`engage.lists:read` / `:write` / `:archive`	Engagement lists and members
`engage.campaigns:read` / `:write` / `:archive`	Engagement campaigns and drafts
`engage.queue:read`	Read the engagement send queue
`engage.queue:send`	Send approved engagement messages and start campaigns (REST only)
`engage.replies:read`	Read engagement replies

Only the canonical names above are accepted. Legacy request names such as engage:read, plans:delete, and accounts:delete are no longer recognized; existing grants that used them were rewritten to their canonical equivalents.

`partners:` is an alias for `accounts:`

The account object was briefly called a “partner”, and its scopes were partners:read, partners:write, and partners:archive. Those names still work: each resolves one-to-one to the matching accounts:* scope at issuance and on every request, so a client that asks for partners:read is granted and stored as accounts:read. New integrations should use accounts:*; the partners:* names are not advertised by GET /api/v1/meta or OAuth discovery. Note the narrowing: in the original legacy vocabulary, accounts:read fanned out to accounts, leads, and relationship maps. It no longer does. accounts:read now means the account family only (accounts and buying groups); request leads:* and relationship_maps:* explicitly. Grants that were already expanded under the old rule keep the extra scopes they were given.

Scope groups

Scopes follow a resource:action pattern:

:read — list and get operations
:write — create and update operations
:archive — archive and delete operations
engage.queue:send — send messages (separate from Engage configuration)

organizations:read is required to discover which organizations a principal can access. users:read is required to list organization users.

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.templates:read
engage.lists:read
engage.campaigns:read
engage.campaigns:write
engage.queue:read
engage.queue:send

MCP tools by scope

The MCP server exposes the same catalog as the REST API. Outbound Engage send and campaign start stay REST-only.

MCP tool	Required scope
`getMeta`	none
`listOrganizations`, `setActiveOrganization`, `getActiveOrganization`, `getOrganization`	`organizations:read`
`listOrganizationUsers`	`users:read`
`listAccounts`, `getAccount`	`accounts:read`
`createAccount`, `updateAccount`, `bulkCreateAccounts`	`accounts:write`
`deleteAccount`	`accounts:archive`
`listAccountContacts`, `getContact`	`contacts:read`
`createAccountContact`, `updateContact`	`contacts:write`
`deleteContact`	`contacts:archive`
`listOpportunities`, `getOpportunity`	`opportunities:read`
`createOpportunity`, `updateOpportunity`	`opportunities:write`
`deleteOpportunity`	`opportunities:archive`
`listLeads`, `getLead`, `listAccountLeads`	`leads:read`
`listCalendarEvents`, `getCalendarEvent`	`calendar:read`
`getCalendarEventSummary`	`calls:read`
`getCalendarEventActionItems`	`action_items:read`
`getCalendarEventTranscript`	`transcripts:read`
`updateCalendarEvent`	`calendar:write`
`getAccountInbox`, `getAccountInboxThreadMessages`, `getAccountInboxSlackThread`	`inbox:read`
`getCommunicationAnalytics`	`analytics:read`
`listNeedsAttention`	`feed:read`

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 tool input params.organizationId
A saved MCP setActiveOrganization choice after listOrganizations

MCP automatically defaults to the sole accessible organization. Saved choices apply to the same user and token across reconnects and new chats. For user-backed tokens, Forecastable also checks the user’s role in that organization. Selecting an organization the user cannot read fails with 403 forbidden.

Errors

Error	Cause
`403 forbidden`	Token is valid but missing the scope required for the endpoint or tool, or the user’s current role does not grant it
`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

`partners:` is an alias for `accounts:`

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

​partners:* is an alias for accounts:*

​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

`partners:` is an alias for `accounts:`

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