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

# OAuth overview

> `oauth()` adds social sign-in via OAuth 2.0 with PKCE. Covers provider setup, token exchange, account linking, session creation, and adding custom providers.

The `oauth()` plugin adds social sign-in to KavachOS using OAuth 2.0 authorization code flow with PKCE. It handles token exchange, account linking, and session creation automatically.

## Built-in providers

<CardGroup cols={2}>
  <Card title="Google" href="/auth/google" />

  <Card title="GitHub" href="/auth/github" />

  <Card title="Apple" href="/auth/apple" />

  <Card title="Discord" href="/auth/discord" />

  <Card title="Slack" href="/auth/slack" />

  <Card title="Microsoft" href="/auth/microsoft" />

  <Card title="GitLab" href="/auth/gitlab" />

  <Card title="LinkedIn" href="/auth/linkedin" />
</CardGroup>

## Generic setup

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

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

The callback URL registered with each provider follows the pattern:

```
https://auth.example.com/auth/oauth/{providerId}/callback
```

## The sign-in flow

1. Your frontend redirects to `/auth/oauth/{providerId}/authorize`. KavachOS generates a state parameter and PKCE challenge, then redirects to the provider.
2. The provider redirects back with an authorization code.
3. KavachOS exchanges the code for tokens, fetches the user profile, and creates or updates the user record.
4. A session cookie is set and the user lands on your redirect destination.

The user ID is stable: the same provider account always resolves to the same row in `kavach_users`.

## Account linking

When a sign-in email matches an existing user, KavachOS links the OAuth identity to that account automatically. A single user can connect multiple providers.

```typescript theme={"system"}
// Check connected providers
const connections = await kavach.auth.getOAuthConnections(userId);

// Disconnect a provider (requires at least one remaining sign-in method)
await kavach.auth.disconnectOAuth(userId, 'github');
```

<Warning>
  Auto-linking trusts the email from the provider. If your threat model requires stronger guarantees, set `autoLink: false` and handle linking explicitly.
</Warning>

## Custom providers

Any OAuth 2.0 provider works by supplying the authorization and token endpoints:

```typescript theme={"system"}
oauth({
  providers: [
    {
      id: 'linear',
      clientId: process.env.LINEAR_CLIENT_ID!,
      clientSecret: process.env.LINEAR_CLIENT_SECRET!,
      authorizationUrl: 'https://linear.app/oauth/authorize', // [!code highlight]
      tokenUrl: 'https://api.linear.app/oauth/token', // [!code highlight]
      userInfoUrl: 'https://api.linear.app/graphql', // [!code highlight]
      scopes: ['read'], // [!code highlight]
      getUserProfile: (data) => ({ // [!code highlight]
        id: data.data.viewer.id,
        email: data.data.viewer.email,
        name: data.data.viewer.name,
      }), // [!code highlight]
    },
  ],
})
```

`getUserProfile` maps the raw provider response to `{ id, email?, name?, image? }`. The `id` is the provider-side user ID, stored for deduplication.