> ## 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.

# OAuth apps

> Register OAuth clients for third-party integrations and user-delegated access.

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](/developers/mcp).

## 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](/developers/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](https://app.forecastable.com/settings/apps).

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

For Claude custom connectors, add this redirect URL:

```text theme={null}
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:

```text theme={null}
https://app.forecastable.com/.well-known/oauth-authorization-server
```

The metadata includes:

```json theme={null}
{
  "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`

```http theme={null}
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.

```mermaid theme={null}
sequenceDiagram
  participant User
  participant Client as OAuth client
  participant Forecastable

  Client->>Forecastable: GET /api/v1/oauth/authorize (client_id, redirect_uri, scope, code_challenge)
  Forecastable->>User: Sign in (if needed) and consent screen
  User->>Forecastable: Allow
  Forecastable->>Client: Redirect with authorization code
  Client->>Forecastable: POST /api/v1/oauth/token (code, code_verifier, client credentials)
  Forecastable->>Client: access_token (Bearer)
  Client->>Forecastable: MCP or REST requests with Bearer token
```

### 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:

```json theme={null}
{
  "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:

```text theme={null}
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.

## Consent screen

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:

```http theme={null}
Authorization: Bearer fcat_YOUR_ACCESS_TOKEN
X-Organization-Id: YOUR_ORGANIZATION_ID
```

The same [scope](/developers/scopes) 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](/developers/mcp) → **Claude Desktop** tab.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Redirect URI mismatch">
    Add the exact callback URL the client uses to the OAuth app **Redirect URLs** list and save.
  </Accordion>

  {' '}

  <Accordion title="Invalid client credentials">
    Confirm the client ID and secret match the OAuth app. Regenerate the secret in Forecastable if
    needed, then update the client.
  </Accordion>

  {' '}

  <Accordion title="PKCE or resource errors">
    Authorization requests must use `code_challenge_method=S256` and
    `resource=https://app.forecastable.com/mcp` for MCP integrations.
  </Accordion>

  <Accordion title="Insufficient scope">
    Add the missing scopes on the OAuth app, save, and have the user reconnect so they can approve the updated permissions.
  </Accordion>
</AccordionGroup>

## Related guides

<Card title="API keys" icon="key" href="/developers/api-keys">
  Static bearer tokens for integrations you control directly.
</Card>

<Card title="Scopes" icon="list" href="/developers/scopes">
  Approved scopes and what each permission allows.
</Card>

<Card title="Rate limits" icon="gauge" href="/developers/rate-limits">
  Per-token limits, 429 responses, and retry behavior.
</Card>