# Fix Notion OAuth failing with restricted_to_workspace

## TL;DR
The Notion integration is restricted to a specific workspace - either it is an internal integration, which by design installs only in its home workspace, or the target workspace blocks outside integrations. Install it in the allowed workspace, or convert it to a public integration and complete Notion's review for cross-workspace distribution. The workspace admin decides which path applies.

## The error
```text
OAuth callback error: "restricted_to_workspace"
The integration cannot be installed in this workspace
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=notion%20oauth%20restricted_to_workspace%20install%20error"
```

## Fix it

### Step 1: Check the integration type

```bash
Open notion.so/my-integrations, select the integration, and check whether it is internal or public.
```

Expected: the type is confirmed. Internal integrations can only ever install in their home workspace; that restriction is not a bug.

### Step 2: Install in the correct workspace if internal is fine

```bash
Have a workspace owner of the home workspace add the integration under Settings / Connections.
```

Expected: the install succeeds there. If the product only ever serves one workspace, stop here.

### Step 3: Convert to public for multi-workspace distribution

```bash
In the integration settings, change the distribution to public and submit it for Notion's review.
```

Expected: after approval, the integration installs in any workspace. Plan for review time; it is not instant.

### Step 4: Check the target workspace's integration policy

```bash
In the target workspace's Settings, confirm whether workspace owners allow public integrations or require approval for each one.
```

Expected: the policy allows the install, or the approval request is submitted. A workspace-level block overrides everything else.

### Step 5: Retry the OAuth flow from the right workspace

```bash
Start the OAuth flow while acting in the correct workspace context and complete the authorization.
```

Expected: authorization completes and the token works.

## When this applies

- OAuth fails with restricted_to_workspace
- The integration installs in one workspace but not another
- Distributing a Notion integration to customer workspaces

## When it doesn't

- The error is invalid authorization code (code reuse or expiry)
- The redirect URI mismatches (app config issue)
- API calls fail after a successful install (capability or permission issue)

## Compatibility

Notion API OAuth 2.0, internal vs public integrations.

## Variant phrasings

### notion integration restricted to workspace

Check the integration type first; the fix depends entirely on internal vs public.

### notion oauth error restricted_to_workspace

The error names the restriction. Match the distribution model to where it must install.

## Why it happens

Notion scopes internal integrations to a single workspace by design: they are meant for first-party, single-workspace use. Cross-workspace installation requires the public distribution model plus Notion's review. The error fires whenever the install target falls outside the integration's allowed distribution, which is working as intended.

## Edge cases

- Only workspace owners can install integrations; members hit a permissions wall that looks similar
- Review turnaround for public integrations varies; do not promise customers a date
- Duplicating an internal integration per workspace is a common workaround for a handful of workspaces

## If it still fails

- Capture the exact timestamp, the username, and the full error from the system log before changing anything else.
- Reproduce with a single test user so you are not debugging a crowd.
- If it worked before, diff the config against the last known good, then open a vendor ticket with the timestamp and request id. Never send secrets or private keys.

## Prevention

- Track credential and certificate expiry with alerts, not memory.
- Run a synthetic check per app daily so breakage pages you, not a user.
- Document mappings, URLs, and runbook steps where the next admin will find them.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dg56RzQR_nKJCFAnJCiwGQ