Setup new app

Before using any Privy SDK, you’ll need to create a new app in the Privy Dashboard. This will give you an app ID and app secret that you’ll use to authenticate your app with Privy’s APIs.

We recommend creating a new app for each environment (e.g. development, staging, production) to keep your API credentials secure.

Create an app

Get API credentials

Navigate to the Configuration > App settings > Basics tab for your app.

Here you’ll find your:

App ID: A unique identifier for your application. It is a public value that can be safely exposed.
App Secret: A secret key used to authenticate API requests. Do not expose it outside of your backend server.

Privy does not store your app secret. Lost app secrets cannot be recovered and must be re-generated.

If you plan on using Privy for user onboarding, you’ll need to configure the login methods you want to use in your app. All client SDKs require at least one login method to be enabled - follow the steps below to set up different options for your users!

For most apps, we recommend either including alternative login options alongside the following, or enabling Multi-Factor Authentication. This ensures broad accessibility across all regions and that users can continue accessing their accounts in the event that they lose access to one login method.

Privy allows you to log users into their accounts with existing social accounts, such as Google, Twitter, Farcaster, Telegram, and more! Follow the steps below to enable different social account login methods for your users.

OAuth login methods

Privy allows you to log users in with their existing social accounts via the OAuth 2.0 protocol. Privy currently supports many of the most popular OAuth providers (Google, Twitter, etc.) — follow the guide below in order to enable these login methods for your application.

Default vs custom credentials

You can enable OAuth (social) logins quickly by just toggling it on in the Dashboard page. This will use default OAuth credentials that the Privy team has configured with each provider.

However, best practice is to configure your own app’s OAuth credentials for each account type.

Configuring your own OAuth credentials has many benefits:

Your app has more control over security and resiliency.
Your users will see your branding on the social login provider’s authentication screen.

Just getting started with Privy? We recommend you complete your integration in development using Privy’s default credentials first. Before going to production, you can easily swap in your own credentials!

Configure your OAuth credentials

Follow this guide to configure your own app’s OAuth credentials.

1. Setup your OAuth apps for each provider

To configure OAuth credentials for a given provider, first create an OAuth app with your chosen provider, following the provider-specific instructions below.

For all providers, during setup, specify Privy’s OAuth callback endpoint as your redirect URI:

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

Apple

Follow this guide to configure your Apple app, service, and key. Note that Apple differs from the rest of the providers in a few ways. You will need to provide the following to Privy upon completion:

Team ID: the identifier associated with your Apple developer account.
Service ID: this will be used as your Client ID. You can find this value listed under the Identifier field in the Service IDs section:

If you are building a mobile app, you will need to use the App ID instead of the Service ID. This should be the same as your application’s BundleId and should be entered as your Client ID in the privy dashboard. You will still need to create a Sign in with Apple service associated with this App ID.

Key ID: the identifier associated with your key, found in the Keys section of the Apple Developer dashboard.
Key: this private key will be generated alongside the Key ID and will be used as your Signing key. Be sure to copy and paste the entire key with the header and footer into the Signing key input.

If you have an app that has users who have already logged in using Privy’s default credentials, we do not yet support migrating these users. If you’d like to test using your own credentials in a development environment, you can do so by creating a new app and setting your credentials before any Apple users log in.

Discord

Follow this guide to register a developer application. After Creating a Discord app, use the OAuth2 settings to generate a Client Secret and set Redirects. You will need to provide the following to Privy upon completion:

Client ID
Client Secret

GitHub

Follow this guide to create a GitHub OAuth App. Do not enable device flow. You will need to provide the following to Privy upon completion:

Client ID
Client secret

Google

Follow this guide. When you are creating your app, make sure to specify Web App for your app type (it will be treated as a web app in the context of OAuth since you are using Privy). You will need to provide the following to Privy upon completion:

Client ID
Client secret

Instagram

Privy makes use of the Instagram API to allow your users to log in with and connect their Instagram business profiles to a Privy application. Follow this guide to create a Facebook Business application with an associated Instagram product, from which you can access the Instagram API with Instagram Login. After creating the Instagram product, use the OAuth2 settings to generate a Client Secret and set Redirects. You will need to provide the following to Privy upon completion:

Client ID
Client Secret

Please note that this is the Client ID and Secret associated with the Instagram Product associated with your Facebook app, and not the Client ID and secret associated with the Facebook app.

The Instagram API only allows for login with Instagram business or creator accounts. Personal Instagram accounts cannot be used to log into Privy applications.

Follow this guide. You will need to provide the following to Privy upon completion:

Client ID
Primary Client Secret

Spotify

Follow this guide to register a developer application. After Creating a Spotify app, use the OAuth2 settings to generate a Client Secret and set Redirects. You will need to provide the following to Privy upon completion:

Client ID
Client Secret

TikTok

Follow the instructions in the ‘Prerequisites’ section of this guide to register your app and enable LoginKit. When you are creating your app, make sure to specify Configure for Web for your app type (it will be treated as a web app in the context of OAuth since you are using Privy).

TikTok is different from other providers in a few key ways:

Your OAuth client_id is referred to as client_key.
You are required to provide a Terms of Service URL and Privacy Policy URL when creating your app.
TikTok conducts a review process, and your new credentials will not work until your app is approved and move to Production status.

You will need to provide the following to Privy upon completion:

Client key (as described above)
Client secret

X (formerly known as Twitter)

Follow this guide to create an X (formerly known as Twitter) app. Make sure to configure your app as a “Confidential client”. In the application authentication settings this is the Web app, Automated App or Bot option for Type of App. You will need to provide the following to Privy upon completion:

Client ID
Client Secret

The X option for Native App doesn’t enforce the use of a Client Secret. This is useful for authenticating with X on your mobile device, without any server involved in the process. You can learn more about Confidential clients in the official X developer documentation.

2. Configure your credentials with Privy

Your custom credentials will go live to all your users as soon as you save them in the dashboard. We highly encourage you to test them in a development app before setting them for your production app.

Navigate to the Login methods page on the Privy dashboard by selecting your app and clicking Login Methods on the side bar. Click on the socials tab to see the social providers. Enter the OAuth credentials under the drop down for you set up.

If a provider does not have a drop down, it does not currently support configuring your own credentials.

3. Configure token return and custom scopes

For any OAuth login method for which you configure your own credentials, you are able to have the user’s OAuth and Refresh access tokens returned to your application’s front by toggling Return OAuth tokens and making use of the useOAuthTokens hook.

If you allow for your application to return OAuth tokens to the front-end, you are also able to configure custom scopes for the OAuth authorization flow, so that the OAuth token returned can be authorized to make API requests beyond the standard scope (such as writes, or authorized access to more granular user data).

It is important that OAuth and refresh tokens are highly sensitive tokens that should be handled and stored in a secure fashion, inaccessible to any other third-party systems. Contact us if you have questions or would like guidance on token management best practices.

Notes

You can update them anytime, with the exception of Apple, LinkedIn, and TikTok.
You can set and save credentials for disabled providers. These credentials will be stored and will be used for that provider’s requests once you enable it.
If you are experiencing an issue after setting your own credentials, you can roll back to using Privy’s default credentials by removing your own from the configuration screen. We only recommend doing this if you are experiencing an issue as moving to use your own credentials is best practice. This will not work for Apple, LinkedIn, or TikTok if you have existing users.

FAQ

Can I delete my custom credentials and go back to using the Privy default ones?

You can remove your credentials from the same page you configured them to go back to using Privy’s defaults. We only recommend doing this if you are experiencing an issue with your own credentials as migrating to your own credentials is the best practice.

For Apple, LinkedIn, and TikTok, once your credentials are in use, you will not be able to reset them due to user migration (see below).

Will migrating to custom credentials impact my users?

For most providers, the change will be undetectable by end users, other than their seeing your app’s name next time the log in (rather than Privy’s). For Apple, LinkedIn, and TikTok, if your app currently uses Privy’s default credentials, we do not support updating to custom credentials. This process requires a migration which we have not yet built.

Can I configure my own custom OAuth provider to work with Privy?

No, we do not support the use of OAuth providers outside of our supported set. If you’d like to use a different provider, you may be able to through the use of custom auth.

Third-Party auth provider

If you plan to use Privy with a custom authentication provider like Auth0, Stytch, or Firebase, use the Third-Party auth page of the dashboard to register the required information from your provider. Otherwise, skip this guide!

Don’t see the Third-Party Auth page in the Dashboard? Please request access to this feature via the Plugins tab on the Integrations page.

To verify your user’s auth status, Privy requires a verification key to ensure the JWTs received by Privy are valid. You must provide one of the following:

JWKS endpoint: If your provider uses JWKS to sign JWTs, provide a JWKS endpoint to allow Privy to get your auth provider’s JWT public key.

{
  "keys": [
    {
      // JWKS
    }
  ]
}

Public Verification Key: If your provider uses a single key to sign JWTs, provide the corresponding public key certificate used for verification.

For Auth0, you can follow these instructions to get these details.

Enable server wallets (optional)

Navigate to the Plugins tab for your app.

Request access to the Server Wallets plugin. Once your request has been approved, when viewing your app in the Dashboard, a Wallet infrastructure section will appear in the sidebar.

Get started

Get started by SDK

Troubleshooting & Tips

Create an app

Get API credentials

Third-Party auth provider

Enable server wallets (optional)

Get started

Get started by SDK

Troubleshooting & Tips

​Create an app

​Get API credentials

​Configure login methods (optional)

​Basic login methods

​Social providers

​Third-Party auth provider

​Enable server wallets (optional)

Create an app

Get API credentials

Configure login methods (optional)

Basic login methods

Social providers

Third-Party auth provider

Enable server wallets (optional)