Custom OAuth

​

Overview

• 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

​

Register your application

1. Navigate to your OAuth provider’s developer console
2. Create a new OAuth application
3. Configure the redirect URI to point to Privy:
   Report incorrect code

   Copy

   Ask AI

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

4. Note your client ID and client secret
5. 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

1. Go to the Twitch Developer Console
2. 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
3. Note the Client ID and generate a Client Secret
4. 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

​

Basic configuration

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

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

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

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

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

​

OAuth endpoints

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

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

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

​

Advanced configuration

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

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

• 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

• Advanced setting for custom domain configurations
• Leave disabled unless specifically needed

​

User information configuration

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

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

• Extract user info directly from access token

​

Field mapping

{
  "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

​

Using Privy UIs

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

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

function CustomTwitchButton() {
  const {initOAuth} = useLoginWithOAuth({
    onSuccess: (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

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>
  );
}