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

# Reddit

> Authenticate users via Reddit OAuth 2.0. Register a web app in Reddit App Preferences, copy the client ID and secret, and configure the `reddit` provider.

## Get credentials

<Steps>
  <Step>
    ### Create an app

    Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps) and scroll to the bottom. Click **Create another app...**. Select **web app** as the type and add your redirect URI:

    ```
    https://auth.example.com/auth/oauth/reddit/callback
    ```
  </Step>

  <Step>
    ### Copy credentials

    After saving, the **client ID** appears directly under the app name (a short string like `abc123XYZ`). Click **edit** to reveal or regenerate the **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: 'reddit', // [!code highlight]
          clientId: process.env.REDDIT_CLIENT_ID!, // [!code highlight]
          clientSecret: process.env.REDDIT_CLIENT_SECRET!, // [!code highlight]
        },
      ],
    }),
  ],
});
```

```bash theme={"system"}
REDDIT_CLIENT_ID=abc123XYZ
REDDIT_CLIENT_SECRET=...
```

## Endpoints

| Endpoint      | URL                                          |
| ------------- | -------------------------------------------- |
| Authorization | `https://www.reddit.com/api/v1/authorize`    |
| Token         | `https://www.reddit.com/api/v1/access_token` |
| User info     | `https://oauth.reddit.com/api/v1/me`         |

## Scopes

Default scope: `identity`

| Scope       | What it unlocks                                        |
| ----------- | ------------------------------------------------------ |
| `identity`  | Read the user's account info (username, avatar, karma) |
| `read`      | Read posts and comments on the user's behalf           |
| `subscribe` | Read and manage subreddit subscriptions                |
| `history`   | Read the user's post and comment history               |

## User data returned

| Field    | Source     | Notes                                                 |
| -------- | ---------- | ----------------------------------------------------- |
| `id`     | `id`       | Stable Reddit account ID (base-36 string)             |
| `email`  | ,          | Not available. Reddit does not expose email via OAuth |
| `name`   | `name`     | Reddit username                                       |
| `avatar` | `icon_img` | Query parameters stripped; may be a default avatar    |

<Warning>
  Reddit does not expose the user's email address via OAuth. If your app requires an email, prompt the user to enter one after sign-in and store it separately.
</Warning>

<Info>
  Reddit's token endpoint uses HTTP Basic authentication rather than posting credentials in the request body. KavachOS handles this automatically.
</Info>

## Handling missing email

Since Reddit provides no email, check for it in your callback handler before creating a user account:

```typescript title="app/api/auth/[...]/route.ts" theme={"system"}
const { userInfo, isNewAccount } = await oauth.handleCallback(
  'reddit', code, state, redirectUri,
);

if (isNewAccount && !userInfo.email) {
  // Redirect to an email-collection step before finalising sign-up.
  return redirect(`/onboarding/email?accountId=${result.account.id}`);
}
```