> ## Documentation Index
> Fetch the complete documentation index at: https://docs.happyuptime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack OAuth

Initiate and complete Slack workspace install via OAuth.

# Slack OAuth

The Slack OAuth flow is normally driven from the dashboard, but the endpoints are exposed for programmatic install (e.g. white-label deployments or Enterprise multi-workspace install).

## Start install

GET `/slack/oauth/install`

Returns a redirect URL to Slack's consent screen.

URL to redirect after success. Default: `/dashboard/integrations/slack`.

```bash
curl -i https://happyuptime.com/api/v1/slack/oauth/install \
  -H "Authorization: Bearer hu_..."
```

```
HTTP/1.1 302 Found
Location: https://slack.com/oauth/v2/authorize?client_id=...&scope=chat:write,channels:read,...&state=...
```

## OAuth callback

GET `/slack/oauth/callback`

Slack redirects here with `code` and `state` query params. Exchanges for an access token, persists the installation, and creates a default alert channel for whichever channel was selected during install.

This endpoint is typically not called manually — it's the redirect URI configured in the Slack app.

## List installations

GET `/slack/installations`

```json
{
  "data": [
    {
      "id": "ins_abc",
      "team_id": "T01XXXX",
      "team_name": "NPC Labs",
      "installed_by": "usr_alice",
      "installed_at": "2026-04-08T14:00:00Z",
      "scopes": ["chat:write", "channels:read", "users:read", ...]
    }
  ]
}
```

## Disconnect

DELETE `/slack/installations/{id}`

Revokes the OAuth grant, removes linked alert channels. Identity links are preserved.

## Required scopes

| Scope | Why |
| --- | --- |
| `chat:write` | Post incident messages |
| `channels:read` | List public channels in picker |
| `commands` | `/happyuptime` slash command |
| `incoming-webhook` | Default install channel |
| `users:read` | List users for identity matching |
| `users:read.email` | Auto-match users by email |
| `im:write` | DM the on-call person |