OAuth

Authenticate users with OAuth social logins including Google, Apple, Twitter, Discord, GitHub, and more

Privy natively supports OAuth login with Google, Apple, Twitter, Discord, GitHub, LinkedIn, Spotify, TikTok, Instagram, Telegram, and LINE. OAuth providers are delegated authentication, meaning a third party controls the authentication flow.

Enable your desired providers in the Privy Dashboard before implementing.

For providers not listed here, use Additional OAuth providers or JWT-based authentication.

Account access is wallet access. If the delegated provider suspends or deletes an account, access to the wallet may be permanently lost. Account compromise at the delegated provider may also allow attackers to access the wallet. Privy recommends requiring MFA with either a passkey or authenticator app to protect against these risks. Set up MFA → | Security checklist →

Implementation

Initializing the login flow

To authenticate users with Privy’s built-in UIs, see UI components. For whitelabel implementations, use initOAuth from the useLoginWithOAuth hook to trigger the OAuth login flow.

initOAuth: ({ provider: OAuthProviderType, disableSignup?: boolean }) => Promise<void>

provider · OAuthProviderType · required

The OAuth provider to use for authentication. Valid values are: 'google', 'apple', 'twitter', 'github', 'discord', 'linkedin', 'spotify', 'tiktok', 'instagram', 'telegram', 'line'.

disableSignup · boolean

If set to true, the OAuth flow will only allow users to log in with existing accounts and prevent new account creation.

Usage

import { useLoginWithOAuth } from '@privy-io/react-auth';

export default function LoginWithOAuth() {
    const { state, initOAuth } = useLoginWithOAuth({
        onComplete: ({ user, isNewUser }) => {
            // user has been successfully authenticated
            if (isNewUser) {
                // Perform actions for new users
            }
        },
        onError: (error) => {
            console.error('Login failed', error);
        }
    });

    return (
        <button
            onClick={() => initOAuth({ provider: 'google' })}
            disabled={state.status === 'loading'}
        >
            {state.status === 'loading' ? 'Logging in...' : 'Log in with Google'}
        </button>
    );
}

Flow state

The state variable returned by useLoginWithOAuth tracks the OAuth flow:

state:
| {status: 'initial'}
| {status: 'loading'}
| {status: 'done'}
| {status: 'error'; error: Error | null};

Callbacks

Pass optional callbacks to useLoginWithOAuth:

onComplete: ({user, isNewUser, wasAlreadyAuthenticated, loginMethod, linkedAccount}) => void
onError: (error: Error) => void

user · User

The user object returned after successful login.

isNewUser · boolean

Whether the user is a new user or an existing user.

wasAlreadyAuthenticated · boolean

Whether the user was already authenticated before the OAuth flow.

loginMethod · string

The login method used (‘google’, ‘apple’, etc.).

linkedAccount · LinkedAccount

The linked account if the user was already authenticated.

Security and tokens

When verifying JWTs from OAuth providers, configure the aud (audience) claim to ensure tokens are intended for your application. See access tokens for details.

Google OAuth may not work in in-app browsers due to Google’s restrictions in embedded webviews.

• Configure allowed OAuth redirect URLs to restrict post-login redirects.
• Access user OAuth and refresh tokens via the useOAuthTokens hook when using your own OAuth credentials.

Resources

React starter repo

Get started with React and Privy.

Next.js starter repo

Get started with Next.js and Privy.

Whitelabel starter repo

Get started with a whitelabel Privy integration.

Telegram Mini App seamless login

Privy supports zero-click authentication for users who open your app from within a Telegram Mini App. When a user opens your app via a Mini App link, Privy detects the Telegram context and authenticates them automatically — no login() call required.

Setup

1. Configure Telegram OAuth credentials and enable seamless authentication in the Privy Dashboard under Telegram settings.
2. Send your app URL to users via a bot message or Mini App link:

bot.send_message(chat_id, 'Log in to demo!', {
  reply_markup: {
    inline_keyboard: [
      [
        {
          text: 'Open app',
          web_app: {url: 'https://your-website-url'}
        }
      ]
    ]
  }
});

You can also use a direct Mini App link (e.g., t.me/your_bot/your_app).

For reference:

• KeyboardButton
• InlineKeyboardButton

Client implementation

No additional client code is required. Privy automatically detects the Mini App context on load and authenticates the user. Your app can read the authenticated user as usual from the usePrivy hook once ready is true.

Configure login methods (optional)

If loginMethods is configured in PrivyProvider, add "telegram":

<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID || ""}
  config={{
    loginMethods: ["email", "google", "telegram"],
  }}
>

Seamless linking within a Mini App

To link a Telegram account to an already-authenticated user from within a Mini App, use linkWithOAuth:

import {usePrivy} from '@privy-io/react-auth';

const {linkWithOAuth} = usePrivy();
await linkWithOAuth({provider: 'telegram'});

To use your app as a Telegram Mini App in the Telegram web client, add http://web.telegram.org and https://web.telegram.org to your allowed domains in the dashboard Settings page.