# Fix GitHub App installation suspended with 403 forbidden

## TL;DR
A suspended GitHub App installation returns 403 because the installation is frozen, not because your token is wrong. Check the installation status on the org or repo settings and unsuspend it. Regenerating tokens will not help while the installation itself is suspended.

## The error
```text
GitHub App installation failed
403 Forbidden: Installation is suspended
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=github app installation suspended 403 forbidden error"
```

## Fix it

### Step 1: Check the installation status

```bash
Open the organization or repository settings -> GitHub Apps -> [app] and look at the installation status.
```

Expected: You see Suspended with a reason or timestamp.

### Step 2: Unsuspend the installation

```bash
Choose unsuspend or restore on the installation.
```

Expected: The status changes to active.

### Step 3: Verify the app's permissions still hold

```bash
Confirm the installation still has the permissions and repository access it needs.
```

Expected: Permissions match what the app requires.

### Step 4: Generate a fresh installation token

```bash
Request a new installation access token now that the installation is active.
```

Expected: Token issuance succeeds.

### Step 5: Retry the failing API calls

```bash
Re-run the calls that returned 403.
```

Expected: They return 200 and the app works again.

## When this applies

- GitHub App API calls fail with 403 on a suspended installation
- An app that worked yesterday returns forbidden today
- You are debugging GitHub App auth failures

## When it doesn't

- The installation is active but calls 403 (check token scopes and expiry)
- The error is 404 (check the installation id)
- The app was never installed (install it first)

## Compatibility

GitHub Apps REST API. Installation tokens as of 2026.

## Variant phrasings

### github app 403 installation suspended

Same condition. Suspension is an installation state; tokens minted against it stay forbidden until unsuspended.

### github app forbidden after suspension

Some 403s linger for a minute after unsuspending while caches clear; retry after a short wait.

### github app installation blocked 403

Blocked by org policy looks similar. Check whether the org restricts the app versus a true suspension.

## Why it happens

Suspending an installation freezes all of its access as a safety control. The API returns 403 for every call because the installation has no rights while suspended, regardless of token validity. Only unsuspending restores access.

## Edge cases

- Suspensions can come from GitHub abuse detection; check the account email for notices
- Unsuspending does not retroactively succeed the calls that failed; replay anything important
- Org owners can suspend apps installed by others; coordinate before debugging tokens

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