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

# Spotify

> Authenticate users with Spotify via `spotifyProvider`. Configures OAuth 2.0 with `user-read-email` and `user-read-private` scopes and supports scope extension.

## Setup

<Steps>
  <Step>
    ### Get credentials

    Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and create an app. Under **Edit Settings**, add your redirect URI:

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

    Copy the **Client ID** and **Client Secret** from the app overview.
  </Step>

  <Step>
    ### Configure

    ```ts theme={"system"}
    import { createKavach, oauth } from 'kavachos';
    import { spotifyProvider } from 'kavachos/auth'; // [!code highlight]

    const kavach = await createKavach({
      database: { provider: 'sqlite', url: 'kavach.db' },
      plugins: [
        oauth({
          providers: [
            spotifyProvider( // [!code highlight]
              process.env.SPOTIFY_CLIENT_ID, // [!code highlight]
              process.env.SPOTIFY_CLIENT_SECRET, // [!code highlight]
            ), // [!code highlight]
          ],
        }),
      ],
    });
    ```
  </Step>
</Steps>

## Environment variables

```bash theme={"system"}
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
```

## Scopes

Default scopes: `user-read-email`, `user-read-private`

To access additional Spotify data, pass a `scopes` array:

```ts theme={"system"}
spotifyProvider(
  process.env.SPOTIFY_CLIENT_ID,
  process.env.SPOTIFY_CLIENT_SECRET,
  { scopes: ['user-read-email', 'user-read-private', 'user-library-read'] }, // [!code highlight]
)
```

<Note>
  The `user-read-email` scope is required to retrieve the user's email address. Without it, the identity will fall back to the Spotify user ID.
</Note>

## Endpoints

| Method | Path                            | Description         |
| ------ | ------------------------------- | ------------------- |
| GET    | `/auth/oauth/authorize/spotify` | Redirect to Spotify |
| GET    | `/auth/oauth/callback/spotify`  | Handle callback     |