Additional OAuth providers

This guide demonstrates how to integrate any custom OAuth 2.0 provider that is not natively supported by Privy. For natively supported providers (Google, Apple, Twitter, Discord, etc.), see the OAuth guide.

This is an advanced feature. We recommend understanding the basics of OAuth 2.0 before proceeding. Misconfiguring this feature can lead to security vulnerabilities.

Overview

Privy’s custom OAuth feature allows you to:

Integrate any OAuth 2.0 provider - Add authentication for services like YouTube, Kraken, or Reddit not natively supported by Privy
Maintain unified user experience - Custom providers work seamlessly with Privy’s existing authentication flows
Customize branding - Upload custom provider icons and display names for your login UI
Advanced configuration - Support for PKCE, custom scopes, and flexible user data mapping

Step 1: Configure your OAuth provider

First, you’ll need to set up your OAuth application with the provider you want to integrate.

Register your application

Navigate to your OAuth provider’s developer console
Create a new OAuth application

Configure the redirect URI to point to Privy:

https://auth.privy.io/api/v1/oauth/callback

Note your client ID and client secret
Review the provider’s documentation for:
- Authorization endpoint URL
- Token endpoint URL
- User info endpoint URL (if needed)
- Available scopes
- User data structure

Example: Setting up Twitch OAuth

Here’s how to configure Twitch as an example:

Go to the Twitch Developer Console
Create a new application with these settings:
- Name: Your app name
- OAuth Redirect URLs: https://auth.privy.io/api/v1/oauth/callback
- Category: Choose appropriate category
Note the Client ID and generate a Client Secret
Review Twitch’s OAuth endpoints:
- Authorization URL: https://id.twitch.tv/oauth2/authorize
- Token URL: https://id.twitch.tv/oauth2/token
- User Info: https://id.twitch.tv/oauth2/userinfo

Step 2: Configure custom OAuth in Privy Dashboard

Navigate to your Privy Dashboard and configure the custom OAuth provider.

Once set, custom OAuth provider fields cannot be changed. Be sure to double check your configuration before saving. Once users are created under a custom OAuth provider, the configuration cannot be deleted.

Basic configuration

Go to Settings > Login methods in your Privy Dashboard
Click Add Custom Provider
Fill in the basic configuration:

Display name (required)

How the provider appears in your login UI
Example: “Twitch”, “Kraken”, “Reddit”

Provider icon

Upload a icon for your login button
Will be displayed alongside other social login options

Client ID (required)

The client ID from your OAuth provider
Used to identify your application during OAuth flow

Client secret (required)

The client secret from your OAuth provider
Securely stored and used for token exchange

OAuth endpoints

Configure the OAuth flow endpoints: Authorization URL (required)

Where users are redirected to grant permissions
Example: https://provider.com/oauth/authorize

Token URL (required)

Endpoint for exchanging authorization code for access token
Also known as the refresh URL
Example: https://provider.com/oauth/token

Profile URL (optional)

Endpoint to fetch user information
Only needed if using “Profile Endpoint” user info source
Example: https://api.provider.com/user

Advanced configuration

Scopes

List of OAuth scopes to request
Common scopes: openid, profile, email
Provider-specific examples:
- Twitch: user:read:email, openid
- Discord: identify, email

Scopes delimiter

Character used to separate multiple scopes
Default: space ( )
Some providers use comma (,) or plus (+)

PKCE enabled

Enable Proof Key for Code Exchange for enhanced security
Recommended for public clients and mobile apps
Check if your OAuth provider supports PKCE before enabling this setting

Use cookie domain for redirect

Advanced setting for custom domain configurations
Leave disabled unless specifically needed

User information configuration

Configure how Privy extracts user data from your OAuth provider. Review your authentication provider’s documentation to determine which method is needed for your use case. ID Token

Extract user info from OpenID Connect ID token
Works with providers that return ID tokens

Profile endpoint

Fetch user info from a dedicated API endpoint
Requires additional HTTP request

Access token JWT

Extract user info directly from access token

Field mapping

Map user data fields from your provider to Privy user attributes using dot notation for nested fields. Review your auth provider’s documentation to determine which fields are available for extraction and tell Privy where to put that information on the user’s linked account.

{
  "path_to_name": "display_name",
  "path_to_username": "login",
  "path_to_email": "user.email",
  "path_to_profile_picture_url": "profile_image_url"
}

Step 3: Implement in your application

Once configured in the Dashboard, your custom OAuth provider works automatically with Privy’s SDKs.

Using Privy UIs

Your custom OAuth provider will appear automatically in Privy’s login UI:

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

function LoginPage() {
  const {ready, authenticated, user} = usePrivy();
  const {login} = useLogin();

  // Custom providers appear automatically in the login modal
  if (!ready) return <div>Loading...</div>;

  if (!authenticated) {
    return <button onClick={login}>Sign in</button>;
  }

  return <UserDashboard user={user} />;
}

Using whitelabel UIs

Your app can also use our whitelabel hooks to login with custom OAuth providers. As a parameter to the initOAuth method, pass an object with provider field set to custom:<your-provider-name>.

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

function CustomTwitchButton() {
  const {initOAuth} = useLoginWithOAuth({
    onComplete: (user) => {
      console.log('Twitch login successful:', user);
    },
    onError: (error) => {
      console.error('Twitch login failed:', error);
    }
  });

  const handleTwitchLogin = () => {
    initOAuth({provider: 'custom:twitch'});
  };

  return (
    <button onClick={handleTwitchLogin}>
      <img src="/twitch-icon.png" alt="Twitch" width="20" height="20" />
      Connect Twitch account
    </button>
  );
}

Accessing custom OAuth account data

Custom OAuth accounts are available in the user object. Filter the linked accounts by type === custom:<your-provider-name> to find the account.

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

function UserProfile() {
  const {user} = usePrivy();

  // Find custom OAuth accounts
  const customAccounts = user?.linkedAccounts?.filter((account) =>
    account.type.startsWith('custom:')
  );

  // Find specific provider account
  const twitchAccount = user?.linkedAccounts?.find((account) => account.type === 'custom:twitch');

  return (
    <div>
      <h2>Connected Accounts</h2>
      {customAccounts?.map((account) => (
        <div key={account.type}>
          <strong>{account.type.replace('custom:', '')}</strong>
          <p>Username: {account.username}</p>
          <p>Email: {account.email}</p>
        </div>
      ))}
    </div>
  );
}

Your app can configure multiple custom OAuth providers with Privy.

Authentication

Using Privy authentication

Using your own authentication

Additional OAuth providers

Overview

Step 1: Configure your OAuth provider

Register your application

Example: Setting up Twitch OAuth

Step 2: Configure custom OAuth in Privy Dashboard

Basic configuration

OAuth endpoints

Advanced configuration

User information configuration

Field mapping

Step 3: Implement in your application

Using Privy UIs

Using whitelabel UIs

Accessing custom OAuth account data

​Overview

​Step 1: Configure your OAuth provider

​Register your application

​Example: Setting up Twitch OAuth

​Step 2: Configure custom OAuth in Privy Dashboard

​Basic configuration

​OAuth endpoints

​Advanced configuration

​User information configuration

​Field mapping

​Step 3: Implement in your application

​Using Privy UIs

​Using whitelabel UIs

​Accessing custom OAuth account data

Overview

Step 1: Configure your OAuth provider

Register your application

Example: Setting up Twitch OAuth

Step 2: Configure custom OAuth in Privy Dashboard

Basic configuration

OAuth endpoints

Advanced configuration

User information configuration

Field mapping

Step 3: Implement in your application

Using Privy UIs

Using whitelabel UIs

Accessing custom OAuth account data