Get started
- About Privy
- Create an account
- Choose your platform
- Configuring Privy Dashboard
Get started by SDK
- React
- React native
- Swift
- Android
- Flutter
- Unity
- NodeJS
- REST API
Changelogs
- SDK changelogs
Troubleshooting and tips
- React
- Using LLMs
Configure login methods
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!
Basic login methods
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 enables your users to log in via email or link verified email addresses to their account. You can enable email login and linking via the Login Methods page of the dashboard.
One-Time Password Authentication
When a user attempts to log in with their email, a one-time password (OTP) will be sent to their email address. This password is valid for 10 minutes and must be entered to complete the authentication process.
Allow/disallow + in email addresses
You can configure whether to allow email addresses containing the + character in the Login Methods page of the dashboard.
This is useful for users who want to use email aliases.
Allowing + in email addresses enables users to create multiple accounts using email aliases with a single base email address. Consider your application’s security requirements when configuring this option.
Privy enables your users to log in via SMS or link verified phone numbers to their account. You can enable SMS login and linking via the Login Methods page of the dashboard.
One-Time Password Authentication
Similar to email authentication, when a user attempts to log in via SMS, a one-time password (OTP) will be sent to their phone number. This password is valid for 10 minutes and must be entered to complete the authentication process.
Region support
US- and Canada-only region support is included at no additional cost on all plans (Developer, Pro, and Enterprise).
You can request access to international SMS via the Login Methods page of the dashboard. Once approved, international SMS will automatically be enabled for all apps on your account. International region support is available on the Enterprise plan.
If you enable SMS login, you may be responsible for additional charges per SMS sent. Underlying Twilio network costs will be passed through directly. See Twilio’s pricing page here.
International region support
You can request access to international SMS via the Login Methods page of the dashboard. By default, Privy supports the following regions for the international SMS plan:
Region support is subject to change. If you would like to request access to additional SMS regions for your account, please reach out to [email protected]!
Privy supports blockchain wallet-based authentication methods that allow users to securely connect using their existing wallets.
Supported wallet types
Currently, Privy supports both Sign in with Ethereum (SIWE) and Sign in with Solana (SIWS) to authenticate your user into the application with any EVM or SVM compatible wallet.
We’re actively working to expand our support for other networks, such as Bitcoin, Sui, etc. Interested in a specific network that isn’t currently supported? Contact us at [email protected] to inquire about additional chain support or to discuss your specific use case requirements.
Restrict Users to a Single Wallet
You can enable the Restrict users to linking a single third-party wallet option for your application.
When enabled, users can only link one wallet to their account, preventing potential confusion or security issues that might arise from multiple linked wallets.
Social providers
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.
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
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.
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 theIdentifierfield in theService IDssection:
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
Keyssection of the Apple Developer dashboard. - Key: this private key will be generated alongside the
Key IDand will be used as yourSigning key. Be sure to copy and paste the entire key with the header and footer into theSigning keyinput.
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.
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.
Follow this guide. You will need to provide the following to Privy upon completion:
- Client ID
- Primary Client Secret
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 LinkedIn users log in.
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_idis referred to asclient_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
Productionstatus.
You will need to provide the following to Privy upon completion:
- Client key (as described above)
- Client secret
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 TikTok users log in.
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.
Setting up Twitter OAuth 1.0a
To configure OAuth 1.0a for X integration with Privy, first ensure your X developer account has at least Basic tier access, as OAuth 1.0a is only available for this tier and higher.
Then, configure your app’s permissions to match your integration needs (Read or Read and Write).
Once you have completed setting up your Twitter app to allow for OAuth 1.0a authorization, you will need to provide the following to Privy in the dashboard:
- Consumer API Key
- Consumer API Secret
Which OAuth version should I use?
This guide explains the differences between OAuth 2.0 and OAuth 1.0a to help you determine which is most appropriate for your implementation. You can also read more about the differences between the 2 versions in the X API docs.
OAuth 2.0
OAuth 2.0 is the default authentication flow and recommended for most integrations due to its simplicity and ease of setup.
Advantages
- Simple Implementation: This flow is straightforward to set up and implement.
- Granular Permission Scopes: You can specify which permissions to request (e.g.,
users.tweet.read,users.tweet.write).
Limitations
- API Restriction: OAuth 2.0 tokens can only access the X v2 API, not the v1.1 API.
- App-wide Rate Limits: Rate limits are enforced across your entire application rather than per user.
- For example, if the
users/meendpoint has a rate limit of 450 requests per 15 minutes, and 500 users attempt to authenticate, the last 50 users would be rate-limited and unable to complete the login process.
- For example, if the
OAuth 1.0a
OAuth 1.0a provides a different authentication approach with user-specific access tokens and separate rate limits.
Advantages
- User-Specific Rate Limits: Each user’s API usage is rate-limited individually, preventing one user’s activity from affecting others.
- Broader API Access: OAuth 1.0a tokens can access both v2 and v1.1 APIs.
- Isolated User Authorization: Returns user-specific access tokens with either read-only or read-write permissions.
Limitations
- Less Granular Permissions: OAuth 1.0a offers less specific permission control—tokens typically grant either full read access, full read-write access, or no authorization.
- Higher Tier Requirement: Only supported for X developer accounts with Basic tier or higher.
- Implementation Complexity: Creating OAuth signatures for API requests requires additional code and setup compared to OAuth 2.0.
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.
Telegram Login
Follow this guide to create a telegram bot. After creating a Telegram bot, you must set your domain using the /setdomain command in the @BotFather chat. You will need to provide the following to Privy via the Privy Dashboard upon completion:
- Bot token (eg:
1234567890:AzByCxDwEvFuGtHsIr1k2M4o5Q6s7U8w9Y0) - Bot handle (eg:
@MyBot_bot)
Note that when configuring Telegram login:
- Your domain must be configured as your bot’s allowed domain.
- If you have CSP enforcement, you’ll need to update these directives:
script-srcmust allowhttps://telegram.orgin order to be able to download Telegram’s widget script.frame-srcmust allowhttps://oauth.telegram.orgin order to be able to render Telegram’s widget iframe.
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.
Telegram login requires developers to create a Telegram bot with a bot secret. This bot secret controls the Telegram bot and is also used as a symmetric key for authentication. Control over this key enables a developer to sign over authentication data, meaning compromise of this key puts your users (and their accounts) at risk.
Securing this symmetric key is essential for the security of all of your app’s Telegram logins.
Since you need to set your bot’s allowed domain you’ll need to use a tunneling tool for local development such as Cloudflare tunnels or ngrok.
Learn more about Telegram authentication here.
Farcaster login
Farcaster is a sufficiently decentralized social network whose core social graph is stored on-chain. Users can choose how content they create is stored and it enables unique, composable experiences by enabling users to link their accounts with a wallet of their choosing.
Privy enables your users to easily log in to your app using their Farcaster account. This means you can easily integrate Privy with Farcaster to compose experiences with a user’s existing social graph or network.
Automatically link connected wallets on when logging in with Farcaster
Farcaster accounts generally have associated embedded and verified addresses. By toggling this option, upon logging in with Farcaster, Privy will also add the associated wallet addresses as linked external wallets of the authenticated user.
Log in with Farcaster enables log in and read access to a user’s Farcaster account but does not provide write access to the account. To enable that, follow this guide to enable writing to Farcaster using signers.
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.
Enter the claim from your user’s JWT that contains the user’s unique ID. In most access tokens and identity tokens, this is the sub claim.
aud accepts multiple values. If any of the aud values in the JWT are included in the set of allowed aud values, the JWT will be successfully verified.
When a user logs into your app, your auth provider issues them an access and/or an
identity token to represent their auth status. To provision your user’s embedded wallet,
Privy must validate this token to authenticate your user. Privy will verify both the token’s
signature and its expiration time
(exp claim).