# Fix Notion OAuth integration revoked by the user

## TL;DR
When a user revokes a Notion integration, every token for it dies immediately. Detect the revocation from the API error, tell the user to reconnect, and send them through the OAuth flow again. There is no way to resurrect the old tokens.

## The error
```text
Notion API call failed
{"object":"error","status":401,"code":"unauthorized","message":"The integration was revoked"}
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=notion oauth integration revoked by user error"
```

## Fix it

### Step 1: Confirm the revocation

```bash
Make an API call with the stored token and read the error.
```

Expected: The error names revocation rather than a bad token.

### Step 2: Mark the connection as disconnected in your app

```bash
Update the user's integration status to needs-reconnect so your UI reflects reality.
```

Expected: The user sees a reconnect prompt instead of silent failures.

### Step 3: Send the user through OAuth again

```bash
Start a fresh Notion authorization flow for the user.
```

Expected: The user authorizes and you receive a new token.

### Step 4: Store the new token

```bash
Replace the dead token in your store with the new one.
```

Expected: API calls succeed with the new token.

### Step 5: Add revocation handling

```bash
In your API client, treat revocation errors as a reconnect signal, not a retry signal.
```

Expected: Future revocations surface a clean reconnect prompt automatically.

## When this applies

- Notion API calls fail after a user revokes the integration
- A previously working integration suddenly returns 401
- You are building reconnection UX for OAuth integrations

## When it doesn't

- The integration was never authorized (run the first-time flow)
- The error is about page permissions (check what the user shared)
- Tokens work but specific calls fail (check the integration capabilities)

## Compatibility

Notion API OAuth 2.0 integrations.

## Variant phrasings

### notion integration revoked 401

Same failure. Revocation kills the token instantly; only a fresh authorization fixes it.

### notion unauthorized integration revoked

Do not retry revoked tokens with backoff. It will never recover on its own.

### notion reconnect integration after revoke

Reconnection is just the normal OAuth flow run again. Keep the UX to one click.

## Why it happens

Notion lets users revoke integrations from their settings at any time, and revocation immediately invalidates all tokens. Your app finds out the hard way: the next API call fails. This is working as designed; the app must handle the revoked state gracefully.

## Edge cases

- Users often revoke when they leave a team; tie reconnection prompts to workspace changes
- Internal integrations cannot be revoked the same way; know which type you built
- Keep the old token's scopes in mind; the user may authorize fewer capabilities on reconnect

## If it still fails

- Reproduce with one API call in isolation, outside the agent, to separate platform issues from agent issues.
- Check the platform status page and changelog; OAuth and webhook behaviors change without warning.
- Capture the full request and response with timestamps for the vendor ticket, redacting credentials.
- Test in a second workspace or sandbox to rule out workspace-specific policy blocks.
- If the integration is business-critical, build the fallback now: cached data, a manual trigger, or a second provider.

## Prevention

- Store OAuth credentials in a secrets manager with rotation reminders.
- Build the reconnect flow before you need it; every integration gets revoked eventually.
- Log token ages so expiring grants are visible ahead of time.
- Keep a sandbox integration for testing config changes.
- Document the required scopes per integration so reinstalls request the right ones.

## Provenance

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