OAuth - Privy docs

Privy offers the ability to sign up and log users in using OAuth providers. Users can sign in with familiar flows on Google, Apple, Twitter, Github, Discord, LinkedIn, TikTok, Spotify, and Instagram.

Login with OAuth is the onboarding flow your users are used to, integrated into your application in just a few lines of code.

The React SDK supports OAuth login with Google, Apple, Twitter, GitHub, Discord, LinkedIn, Spotify, TikTok, and Instagram. For all other OAuth providers, you can use JWT-based authentication.

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

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, loading, initOAuth } = useLoginWithOAuth();

  const handleLogin = async () => {
      try {
          // The user will be redirected to OAuth provider's login page
          await initOAuth({ provider: 'google' });
      } catch (err) {
          // Handle errors (network issues, validation errors, etc.)
          console.error(err);
      }
  };

  return (
      <div>
          <button onClick={handleLogin} disabled={loading}>
              {loading ? 'Logging in...' : 'Log in with Google'}
          </button>
      </div>
  );
}

Tracking Flow State

Track the state of the OAuth flow via the state variable returned by the useLoginWithOAuth hook.

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

status

'initial' | 'loading' | 'done' | 'error'

The current state of the OAuth flow.

error

Error | null

The error that occurred during the OAuth flow (only present when status is ‘error’).

Callbacks

You can optionally pass callbacks to the useLoginWithOAuth hook to run custom logic after a successful login or to handle errors.

`onSuccess`

onSuccess: ({user, isNewUser, wasAlreadyAuthenticated, loginMethod, linkedAccount}) => void

Parameters

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.

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

linkedAccount

LinkedAccount

The linked account if the user was already authenticated.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the OAuth flow.

Example with Callbacks

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

export default function LoginWithOAuth() {
    const { initOAuth } = useLoginWithOAuth({
        onSuccess: ({ user, isNewUser }) => {
            console.log('User logged in successfully', user);
            if (isNewUser) {
                // Perform actions for new users
            }
        },
        onError: (error) => {
            console.error('Login failed', error);
        }
    });

    return (
        <button onClick={() => initOAuth({ provider: 'google' })}>
            Log in with Google
        </button>
    );
}

Security

We recommend configuring allowed OAuth redirect URLs to restrict where users can be redirected after they log in with an external OAuth provider. Learn more here!

The React SDK supports OAuth login with Google, Apple, Twitter, GitHub, Discord, LinkedIn, Spotify, TikTok, and Instagram. For all other OAuth providers, you can use JWT-based authentication.

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

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, loading, initOAuth } = useLoginWithOAuth();

  const handleLogin = async () => {
      try {
          // The user will be redirected to OAuth provider's login page
          await initOAuth({ provider: 'google' });
      } catch (err) {
          // Handle errors (network issues, validation errors, etc.)
          console.error(err);
      }
  };

  return (
      <div>
          <button onClick={handleLogin} disabled={loading}>
              {loading ? 'Logging in...' : 'Log in with Google'}
          </button>
      </div>
  );
}

Tracking Flow State

Track the state of the OAuth flow via the state variable returned by the useLoginWithOAuth hook.

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

status

'initial' | 'loading' | 'done' | 'error'

The current state of the OAuth flow.

error

Error | null

The error that occurred during the OAuth flow (only present when status is ‘error’).

Callbacks

You can optionally pass callbacks to the useLoginWithOAuth hook to run custom logic after a successful login or to handle errors.

`onSuccess`

onSuccess: ({user, isNewUser, wasAlreadyAuthenticated, loginMethod, linkedAccount}) => void

Parameters

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.

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

linkedAccount

LinkedAccount

The linked account if the user was already authenticated.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the OAuth flow.

Example with Callbacks

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

export default function LoginWithOAuth() {
    const { initOAuth } = useLoginWithOAuth({
        onSuccess: ({ user, isNewUser }) => {
            console.log('User logged in successfully', user);
            if (isNewUser) {
                // Perform actions for new users
            }
        },
        onError: (error) => {
            console.error('Login failed', error);
        }
    });

    return (
        <button onClick={() => initOAuth({ provider: 'google' })}>
            Log in with Google
        </button>
    );
}

Security

We recommend configuring allowed OAuth redirect URLs to restrict where users can be redirected after they log in with an external OAuth provider. Learn more here!

The React Native (Expo) SDK supports OAuth login with Google, Apple, Twitter, GitHub, Discord, LinkedIn, Spotify, TikTok, and Instagram. For all other OAuth providers, you can use JWT-based authentication.

Privy supports native Apple login when running on iOS. To configure native Apple login, follow this guide.

Use login from the useLoginWithOAuth hook to authenticate users using an OAuth provider.

login: ({
  provider: OAuthProviderType,
  disableSignup?: boolean
}) => Promise<PrivyUser>

Parameters

provider

OAuthProviderType

required

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

If true, the OAuth flow will only allow existing users to log in, preventing new account creation.

Response

user

PrivyUser

The user object returned after successful login.

Usage

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

export function LoginButton() {
  const { login, state } = useLoginWithOAuth();

  return (
    <Button
      onPress={() => login({ provider: 'google' })}
      disabled={state.status === 'loading'}
    >
      {state.status === 'loading' ? 'Logging in...' : 'Login with Google'}
    </Button>
  );
}

Tracking Flow State

Track the state of the OAuth flow via the state variable returned by the useLoginWithOAuth hook.

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

status

'initial' | 'loading' | 'done' | 'error'

The current state of the OAuth flow.

error

Error | null

The error that occurred during the OAuth flow (only present when status is ‘error’).

Usage: Conditional Rendering

import { View, Text, Button } from 'react-native';
import { usePrivy, useLoginWithOAuth, hasError } from '@privy-io/expo';

export function LoginScreen() {
  const { user } = usePrivy();
  const { state, login } = useLoginWithOAuth();

  return state.status === 'done' ? (
    <View>
      <Text>You logged in successfully</Text>
    </View>
  ) : (
    <View>
      <Button
        disabled={state.status === 'loading'}
        onPress={() => login({ provider: 'google' })}
        title={state.status === 'loading' ? 'Logging in...' : 'Login with Google'}
      />

      {hasError(state) && (
        <Text>Error: {state.error.message}</Text>
      )}
    </View>
  );
}

Callbacks

You can optionally pass callbacks to the useLoginWithOAuth hook to run custom logic after a successful login or to handle errors.

`onSuccess`

onSuccess: (user: PrivyUser, isNewUser: boolean) => Promise<void>

Parameters

user

PrivyUser

The user object returned after successful login.

isNewUser

boolean

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

`onError`

onError: (error: Error) => Promise<void>

Parameters

error

Error

The error that occurred during the OAuth flow.

Usage with Callbacks

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

export function LoginScreen() {
  const { login } = useLoginWithOAuth({
    onSuccess(user, isNewUser) {
      console.log('Logged in successfully', { user, isNewUser });
      // Navigate to home screen, show welcome message, etc.
    },
    onError(error) {
      console.error('Login failed', error);
      // Show error message
    }
  });

  return (
    <Button
      onPress={() => login({ provider: 'google' })}
      title="Login with Google"
    />
  );
}

To authenticate a user via an OAuth account (e.g. Google), use the Privy client’s oAuth handler.

The Swift SDK supports OAuth login with Google, Apple, and Twitter. For all other OAuth providers, you can use JWT-based authentication.

Privy supports native Apple login when running on iOS. To configure native Apple login, follow this guide.

Prior to integrating OAuth login, make sure you have properly configured your app’s allowed URL schemes in the Privy dashboard. Login with OAuth will not work if you have not completed this step.

To launch the oAuth flow, simply call privy.oAuth.login. As parameters to this method, pass the following fields:

provider

OAuthProvider

required

A member of the OAuthProvider enum specifying which OAuth provider the user should login with. Currently, .google, .apple and .twitter are supported.

appUrlScheme

String

(Optional). Your app’s URL scheme as a string. If you do not pass this value, Privy will use the first valid app URL scheme from your app’s info.plist.

Returns

PrivyUser

The authenticated Privy user

Throws

An error if logging the user in is unsuccessful.

Usage

do {
    let privyUser = try await privy.oAuth.login(with: OAuthProvider.google, appUrlScheme: "privyiosdemo")
} catch {
    print("OAuth login error: \(error)")
}

That’s it! If your user was successfully authenticated, the login method will return the new AuthSession.

Handling errors

An error could be thrown if:

Your app url scheme is not explicitly provided or set in your info.plist
Your app url scheme is not registered in the Privy dashboard.
There was an issue generating the OAuth provider login URL
The user declined or cancelled the login attempt, or there was another error during authentication

If an error is thrown, you can get a description of the error as a string from the error thrown by privy.oAuth.login.

To configure native apple login, follow this guide.

To authenticate a user via an OAuth account (e.g. Google, Discord, Apple), use the Privy client’s OAuth handler.

This is a two step process, though Privy’s Unity SDK wraps it into a single method call:

Generate an OAuth login URL corresponding to your desired OAuth provider
Redirect the user to the login URL to have them authenticate with the chosen OAuth provider

Supported OAuth Providers

Privy’s Unity SDK currently supports OAuth login with Google, Apple and Discord. For all other OAuth providers, you can use JWT-based authentication.

Configure allowed URL schemes

Prior to integrating OAuth login, make sure you have properly configured your app’s allowed URL schemes in the Privy dashboard.

For non-web platforms, be sure to setup deeplinking with your allowed URL scheme.

To launch the OAuth flow, simply call PrivyManager.Instance.OAuth.LoginWithProvider. As parameters to this method, pass the following fields:

provider

OAuthProvider

required

A member of the OAuthProvider enum specifying which OAuth provider the user should login with.

redirectUri

String

required

For WebGL builds, this will be your redirect URL. For applications, this will be your app’s URL scheme.

Usage

try
{
    // Log the user in with Google OAuth
    await PrivyManager.Instance.OAuth.LoginWithProvider(OAuthProvider.Google, "myappscheme");
}
catch
{
    // Login with OAuth was unsuccessful
    Debug.Log("Error logging user in.");
}

That’s it! If your user was successfully authenticated, the LoginWithProvider method will return the new AuthState for a user.

This method will throw an error if:

a redirectUri is not provided
the network call to authenticate the user fails

User authentication

​Usage

​Tracking Flow State

​Callbacks

​onSuccess

​Parameters

​onError

​Parameters

​Example with Callbacks

​Security

​Usage

​Tracking Flow State

​Callbacks

​onSuccess

​Parameters

​onError

​Parameters

​Example with Callbacks

​Security

​Parameters

​Response

​Usage

​Tracking Flow State

​Usage: Conditional Rendering

​Callbacks

​onSuccess

​Parameters

​onError

​Parameters

​Usage with Callbacks

​Initializing the login flow

​Returns

​Throws

​Usage

​Handling errors

​Native Apple login

​Supported OAuth Providers

​Configure allowed URL schemes

​Initializing the login flow

​Usage

Usage

Tracking Flow State

Callbacks

`onSuccess`

Parameters

`onError`

Parameters

Example with Callbacks

Security

Usage

Tracking Flow State

Callbacks

`onSuccess`

Parameters

`onError`

Parameters

Example with Callbacks

Security

Parameters

Response

Usage

Tracking Flow State

Usage: Conditional Rendering

Callbacks

`onSuccess`

Parameters

`onError`

Parameters

Usage with Callbacks

Initializing the login flow

Returns

Throws

Usage

Handling errors

Native Apple login

Supported OAuth Providers

Configure allowed URL schemes

Initializing the login flow

Usage