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

# Twitch

> Authenticate users with their Twitch account via the `oauth` plugin. Covers Developer Console setup and the `user:read:email` scope for profile access.

## Get credentials

<Steps>
  <Step>
    ### Register an application

    Go to the [Twitch Developer Console](https://dev.twitch.tv/console/apps) and click **Register Your Application**. Set the **OAuth Redirect URL** to:

    ```
    https://auth.example.com/auth/oauth/twitch/callback
    ```

    Pick any category, **Website Integration** works for most apps.
  </Step>

  <Step>
    ### Copy credentials

    After saving, click **Manage** on the app. Copy the **Client ID**. Click **New Secret** to generate and copy the **Client Secret**.
  </Step>
</Steps>

## Configuration

```typescript title="lib/kavach.ts" theme={"system"}
import { createKavach } from 'kavachos';
import { oauth } from 'kavachos/auth';

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    oauth({
      providers: [
        {
          id: 'twitch', // [!code highlight]
          clientId: process.env.TWITCH_CLIENT_ID!, // [!code highlight]
          clientSecret: process.env.TWITCH_CLIENT_SECRET!, // [!code highlight]
        },
      ],
    }),
  ],
});
```

```bash theme={"system"}
TWITCH_CLIENT_ID=abcdef1234567890abcdef1234567890
TWITCH_CLIENT_SECRET=...
```

## Endpoints

| Endpoint      | URL                                     |
| ------------- | --------------------------------------- |
| Authorization | `https://id.twitch.tv/oauth2/authorize` |
| Token         | `https://id.twitch.tv/oauth2/token`     |
| User info     | `https://api.twitch.tv/helix/users`     |

## Scopes

Default scope: `user:read:email`

| Scope                        | What it unlocks                        |
| ---------------------------- | -------------------------------------- |
| `user:read:email`            | Read the user's verified email address |
| `user:read:follows`          | Read the channels the user follows     |
| `channel:read:subscriptions` | Read the user's channel subscriptions  |

## User data returned

| Field    | Source                      | Notes                                             |
| -------- | --------------------------- | ------------------------------------------------- |
| `id`     | `data[0].id`                | Stable numeric Twitch user ID                     |
| `email`  | `data[0].email`             | Only present with `user:read:email` scope         |
| `name`   | `data[0].display_name`      | Localized display name (may differ from login)    |
| `avatar` | `data[0].profile_image_url` | Direct CDN URL; changes when user updates profile |

<Info>
  The Twitch Helix API requires a `Client-ID` header on every request alongside the Bearer token. KavachOS handles this automatically, you do not need to set it manually.
</Info>

<Warning>
  Twitch email addresses may not be verified. Check the `broadcaster_type` and account age in the raw response if you need higher assurance.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="OAuth overview" href="/auth/oauth" icon="key">
    Generic OAuth configuration and custom provider setup.
  </Card>

  <Card title="Google" href="/auth/google" icon="google">
    Another popular social provider with verified email addresses.
  </Card>

  <Card title="GitHub" href="/auth/github" icon="github">
    Developer-focused OAuth provider with org membership scopes.
  </Card>

  <Card title="Reddit" href="/auth/reddit" icon="reddit">
    Social provider in the same nav group.
  </Card>
</CardGroup>