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

# Twitter / X

> Authenticate users with Twitter/X via `createTwitterProvider`. Covers OAuth 2.0 PKCE, Developer Portal configuration, and `users.read` and `tweet.read` scopes.

## Setup

<Steps>
  <Step>
    ### Get credentials

    Go to the [Twitter Developer Portal](https://developer.twitter.com) and create a project and app. Under **User authentication settings**, enable OAuth 2.0 and set the redirect URI to:

    ```
    https://your-app.com/api/kavach/auth/oauth/callback/twitter
    ```

    Set the app type to **Web App** and enable **Read** permissions at minimum.
  </Step>

  <Step>
    ### Configure

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

    const kavach = await createKavach({
      database: { provider: 'sqlite', url: 'kavach.db' },
      plugins: [
        oauth({
          providers: [
            createTwitterProvider({
              clientId: process.env.TWITTER_CLIENT_ID!,
              clientSecret: process.env.TWITTER_CLIENT_SECRET!,
            }),
          ],
        }),
      ],
    });
    ```

    ```bash theme={"system"}
    TWITTER_CLIENT_ID=...
    TWITTER_CLIENT_SECRET=...
    ```
  </Step>
</Steps>

## Scopes

Default scopes: `users.read`, `tweet.read`

| Scope            | What it unlocks         |
| ---------------- | ----------------------- |
| `users.read`     | Read the user's profile |
| `tweet.read`     | Read tweets             |
| `offline.access` | Refresh token support   |

<Warning>
  Twitter does not return an email address through the standard OAuth 2.0 flow. KavachOS uses a synthetic non-deliverable address (`username@twitter.invalid`) as a placeholder. Do not treat it as a real email.
</Warning>

## Endpoints

| Method | Path                            | Description         |
| ------ | ------------------------------- | ------------------- |
| GET    | `/auth/oauth/authorize/twitter` | Redirect to Twitter |
| GET    | `/auth/oauth/callback/twitter`  | Handle callback     |