OAuth apps

OAuth apps let third-party clients access Forecastable on behalf of signed-in users. Each app has a client_id, client_secret, approved scopes, optional redirect URIs, and optional organization access limits. Use OAuth when an external product must run an authorization flow — for example, Claude custom connectors connecting to the Forecastable MCP server.

When to use OAuth

Use an OAuth app when:

users sign in to Forecastable and approve access themselves
a third-party client exchanges an authorization code for an access token
you need per-user delegated access instead of a single static API key

Use API keys for integrations that cannot run an OAuth consent flow, such as scripts or MCP clients that only support static bearer tokens.

Prerequisites

a Forecastable account with the developer role
access to the organization the OAuth app should be scoped to

Create an OAuth app

Open Settings → Developer → OAuth Apps.

Click Create OAuth App.
Enter an app name and select the organization.
On the app detail page, copy the Client ID and Client secret from Credentials.
Add redirect URLs the client will use after authorization.
Select the scopes the app may request.
Optionally configure display information (icon, name, descriptions) shown on the consent screen.

For Claude custom connectors, add this redirect URL:

https://claude.ai/api/mcp/auth_callback

Redirect URLs are optional on the app until a client needs them. Authorization fails if the client sends a redirect_uri that is not registered on the app. You can regenerate the client secret or signing secret from the app detail page. Regeneration invalidates the previous value immediately.

Dynamic client registration

OAuth-aware MCP clients can create OAuth apps automatically with Dynamic Client Registration. Cursor and Claude custom connectors use this flow so users only enter the connector name and MCP server URL. Clients discover the registration endpoint from:

https://app.forecastable.com/.well-known/oauth-authorization-server

The metadata includes:

{
  "registration_endpoint": "https://app.forecastable.com/api/v1/oauth/register",
  "registration_endpoint_auth_methods_supported": ["none"]
}

Registration accepts authorization-code clients with PKCE. Redirect URIs may be:

any https:// URL (for example Claude or Cursor Agents)
loopback HTTP (http://localhost…, http://127.0.0.1…, http://[::1]…)
Cursor desktop callbacks: cursor://anysphere.cursor-mcp/oauth/callback and cursor-nightly://anysphere.cursor-mcp/oauth/callback

POST /api/v1/oauth/register
Content-Type: application/json

{
  "client_name": "Claude",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "organizations:read accounts:read contacts:read opportunities:read"
}

Forecastable returns a generated client_id and, when token_endpoint_auth_method is not none, a client_secret. The client stores those credentials and uses them during the token exchange. OAuth JSON errors use RFC 6749 shapes ({ "error": "invalid_request", "error_description": "…" }), not the Integration API error envelope.

Authorization code flow (PKCE)

Forecastable supports OAuth 2.0 authorization code with PKCE (S256). This is the flow Claude and other interactive MCP clients use.

Authorize

Unauthenticated users are redirected to Forecastable login, then returned to the authorize URL.

GET /api/v1/oauth/authorize

Required query parameters:

Parameter	Description
`response_type`	Must be `code`
`client_id`	OAuth app client ID (`fcac_…`)
`redirect_uri`	Must match a URL registered on the app
`scope`	Space- or comma-separated scopes (must be allowed on the app)
`code_challenge`	PKCE challenge
`code_challenge_method`	Must be `S256`
`resource`	Must be `https://app.forecastable.com/mcp` for MCP clients
`state`	Recommended CSRF value echoed on redirect

After the user clicks Allow, Forecastable redirects to redirect_uri with ?code=…&state=….

Token exchange

POST /api/v1/oauth/token

For grant_type=authorization_code, send:

Field	Description
`grant_type`	`authorization_code`
`code`	Authorization code from the redirect
`redirect_uri`	Same redirect URI used in authorize
`code_verifier`	PKCE verifier matching `code_challenge`
`client_id` / `client_secret`	App credentials (body or HTTP Basic auth)

Successful response:

{
  "access_token": "fcat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "organizations:read accounts:read"
}

Access tokens expire after one hour. The client must run the authorization flow again to obtain a new token.

Client credentials flow

OAuth apps also support client_credentials for server-to-server access using the app’s client ID and secret, without an end-user login.

POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=organizations:read%20accounts:read

The requested scopes must be a subset of those configured on the OAuth app. Tokens are issued to the app principal, not an individual user session.

Discovery metadata

OAuth-aware clients can read Forecastable metadata from:

https://app.forecastable.com/.well-known/oauth-authorization-server
https://app.forecastable.com/.well-known/oauth-protected-resource

These documents list supported grant types, endpoints, scopes, and the protected MCP resource URL. During authorization, users see:

app name, icon, and description from the OAuth app Display info
the workspace (organization) context
grouped scopes with short explanations
Allow and Cancel actions

Users must already belong to the organization bound to the OAuth app. Approved tokens inherit the app’s allowed scopes and organization access for that user.

Use access tokens

Send issued tokens the same way as API keys:

Authorization: Bearer fcat_YOUR_ACCESS_TOKEN
X-Organization-Id: YOUR_ORGANIZATION_ID

The same scope and organization rules apply to REST endpoints and MCP tools.

Claude custom connector

For step-by-step Claude setup with screenshots, see the MCP server guide → Claude Desktop tab.

Troubleshooting

Redirect URI mismatch

Add the exact callback URL the client uses to the OAuth app Redirect URLs list and save.

Invalid client credentials

Confirm the client ID and secret match the OAuth app. Regenerate the secret in Forecastable if needed, then update the client.

PKCE or resource errors

Authorization requests must use code_challenge_method=S256 and resource=https://app.forecastable.com/mcp for MCP integrations.

Insufficient scope

Add the missing scopes on the OAuth app, save, and have the user reconnect so they can approve the updated permissions.

API keys

Static bearer tokens for integrations you control directly.

Scopes

Approved scopes and what each permission allows.

Rate limits

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

Getting Started

AI

Developers

Integrations

When to use OAuth

Prerequisites

Create an OAuth app

Dynamic client registration

Authorization code flow (PKCE)

Authorize

Token exchange

Client credentials flow

Discovery metadata

Use access tokens

Claude custom connector

Troubleshooting

API keys

Scopes

Rate limits

​When to use OAuth

​Prerequisites

​Create an OAuth app

​Dynamic client registration

​Authorization code flow (PKCE)

​Authorize

​Token exchange

​Client credentials flow

​Discovery metadata

​Consent screen

​Use access tokens

​Claude custom connector

​Troubleshooting

​Related guides

API keys

Scopes

Rate limits

When to use OAuth

Prerequisites

Create an OAuth app

Dynamic client registration

Authorization code flow (PKCE)

Authorize

Token exchange

Client credentials flow

Discovery metadata

Consent screen

Use access tokens

Claude custom connector

Troubleshooting

Related guides