Appearance
Documentation / server-auth / PrivyClient
Class: PrivyClient
The Privy client performs operations against the Privy API.
typescript
import {PrivyClient} from '@privy-io/server-auth';
Constructors
new PrivyClient(appId, appSecret, options)
new PrivyClient(
appId
,appSecret
,options
):PrivyClient
Creates a new Privy client.
Parameters
• appId: string
The app id from your console.
• appSecret: string
The app secret, only visible once on app creation in the console.
• options: Object
= {}
Initialization options.
• options.apiURL?: string
The URL of the Privy API. Defaults to https://auth.privy.io
.
• options.timeout?: number
Time in milliseconds after which to timeout requests to the API. Defaults to 10000
(10 seconds).
Returns
Properties
api
private
api:Http
appId
private
appId:string
verificationKey
private
verificationKey:null
|string
=null
Methods
deleteUser()
deleteUser(
userId
):Promise
<void
>
Delete the user object associated with the given user DID (decentralized ID).
typescript
const user = await client.deleteUser("did:privy:XXXXX");
Parameters
• userId: string
The Privy DID of the user.
Returns
Promise
<void
>
getAllowlist()
getAllowlist():
Promise
<AllowlistEntry
[]>
Get the allowlist entries for a the given app. This is a list of users that are allowed to access the app, if the allowlist is enabled.
typescript
const allowlist = await client.getAllowlist();
Returns
Promise
<AllowlistEntry
[]>
a list of AllowlistEntry objects.
getAppSettings()
getAppSettings():
Promise
<AppSettings
>
Get the app settings associated with the given app.
Returns
Promise
<AppSettings
>
the AppSettings
getTestAccessToken()
getTestAccessToken():
Promise
<Object
>
Get an access token for the test account for your app. Will throw an error if you have not enabled test credentials in the dashboard. Will throw an error if allowed origins or base domain are enabled for the app.
Returns
Promise
<Object
>
accessToken
accessToken:
string
=authenticateResponse.data.token
getUser()
getUser(
userId
):Promise
<User
>
Get the user object associated with the given user DID (decentralized ID).
typescript
const user = await client.getUser("did:privy:XXXXX");
Parameters
• userId: string
The Privy DID of the user.
Returns
Promise
<User
>
A User if the user exists.
getUserByCustomAuthId()
getUserByCustomAuthId(
customUserId
):Promise
<null
|User
>
Gets a user object by their custom JWT auth ID, which is scoped to an individual app.
typescript
const user = await client.getUserByCustomAuthId(customUserId);
Parameters
• customUserId: string
The custom identifier of the user defined by their JWT
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByEmail()
getUserByEmail(
address
):Promise
<null
|User
>
Get the user object associated with an email address.
typescript
const user = await client.getUserByEmail(emailAddress);
Parameters
• address: string
The email address of the user to find.
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByFarcasterId()
getUserByFarcasterId(
fid
):Promise
<null
|User
>
Get the user object associated with a farcaster ID.
typescript
const user = await client.getUserByFarcasterId(fid);
Parameters
• fid: number
The farcaster ID (a number).
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByPhoneNumber()
getUserByPhoneNumber(
number
):Promise
<null
|User
>
Get the user object associated with a phone number.
typescript
const user = await client.getUserByPhoneNumber(number);
Parameters
• number: string
The phone number of the user to find.
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByTelegramUserId()
getUserByTelegramUserId(
telegramUserId
):Promise
<null
|User
>
Get the user object associated with a telegram user ID.
typescript
const user = await client.getUserByTelegramUserId(telegramUserId);
Parameters
• telegramUserId: string
Telegram user ID to search for
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByTelegramUsername()
getUserByTelegramUsername(
username
):Promise
<null
|User
>
Get the user object associated with a telegram username.
typescript
const user = await client.getUserByTelegramUsername(telegramUsername);
Parameters
• username: string
Telegram username to search for
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByTwitterSubject()
getUserByTwitterSubject(
subject
):Promise
<null
|User
>
Get the user object associated with a twitter oauth subject (ID).
typescript
const user = await client.getUserByTwitterSubject(subject);
Parameters
• subject: string
Twitter subject to search for
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByTwitterUsername()
getUserByTwitterUsername(
username
):Promise
<null
|User
>
Get the user object associated with a twitter username.
typescript
const user = await client.getUserByTwitterUsername(username);
Parameters
• username: string
Twitter username to search for
Returns
Promise
<null
| User
>
A User if the user exists.
getUserByWalletAddress()
getUserByWalletAddress(
walletAddress
):Promise
<null
|User
>
Get the user object associated with a wallet address.
typescript
const user = await client.getUserByWalletAddress(walletAddress);
Parameters
• walletAddress: string
The wallet address of the user to find.
Returns
Promise
<null
| User
>
A User if the user exists.
getUsers()
getUsers(undefined)
getUsers():
Promise
<User
[]>
Get the list of users associated with this app.
typescript
const users = await client.getUsers();
Returns
Promise
<User
[]>
A list of users.
getUsers(searchTerm)
getUsers(
searchTerm
):Promise
<User
[]>
Get the list of users associated with this app whose email, phone number, wallet address, name, or username match a search term.
typescript
const users = await client.getUsers("@privy.io");
Parameters
• searchTerm: string
(optional) The value used to search the list of users.
Returns
Promise
<User
[]>
A list of users.
Deprecated
Use custom helper functions to search
getUsers(bulkParams)
getUsers(
bulkParams
):Promise
<User
[]>
Get multiple users associated with this app by email, phone number, and wallet address
typescript
const users = await client.getUsers({
emails: ["[email protected]", "[email protected]"]
});
Parameters
• bulkParams: BulkParams
The values used to search the list of users.
Returns
Promise
<User
[]>
A list of users.
getVerificationKey()
getVerificationKey():
Promise
<string
>
Get the auth token verification key.
Note that the verification key is pulled from app settings for the first time only and then cached. On subsequent calls the cached verification key is returned.
Returns
Promise
<string
>
String holding the verification key.
importUser()
importUser(
importUserInput
):Promise
<User
>
Import existing user data into Privy, including their linked account data.
This allows your users to interact with all their linked accounts normally after your migration to Privy.
typescript
const user = await client.importUser({
createEthereumWallet: false,
createSolanaWallet: false,
linkedAccounts: [
{
"subject": "123456789123456789",
"username": "batman#1234",
"email": "[email protected]",
"type": "discord_oauth"
},
{
"number": "+1 123 456 7890",
"type": "phone"
},
{
"address": "0x3DAF84b3f09A0E2092302F7560888dBc0952b7B7",
"type": "wallet",
"chainType": "ethereum"
}
]);
Parameters
• importUserInput: ImportUserInput
The user object ImportUserInput, containing linked accounts to import.
Returns
Promise
<User
>
The resultant user User object.
inviteToAllowlist()
inviteToAllowlist(
allowlistEntry
):Promise
<AllowlistEntry
>
Add an allowlist entry for the given app, to give that user access.
The allowlist must enabled for the app, otherwise this will fail.
typescript
const entry = await client.inviteToAllowlist({ type: 'email', value: '[email protected]'});
Parameters
• allowlistEntry: AllowlistEntryInput
The [AllowlistEntryInput]([object Object]) to add to the allowlist.
Returns
Promise
<AllowlistEntry
>
the created AllowlistEntry object.
removeFromAllowlist()
removeFromAllowlist(
allowlistEntry
):Promise
<AllowlistEntry
>
Remove an entry from the allowlist for a Privy app.
The allowlist must enabled for the app, otherwise this will fail.
typescript
await client.removeFromAllowlist();
Parameters
• allowlistEntry: AllowlistEntryInput
The [AllowlistEntryInput]([object Object]) to remove from the allowlist.
Returns
Promise
<AllowlistEntry
>
the deleted AllowlistEntry object.
verifyAuthToken()
verifyAuthToken(
token
,verificationKeyOverride
):Promise
<AuthTokenClaims
>
Verify the auth token format, signature, and claims.
Example usage given e.g. a NextApiRequest
request:
typescript
const header = request.headers.authorization;
const token = header.replace(/^Bearer /, '');
const verifiedClaims = await verifyAuthToken(token);
Parameters
• token: string
The auth token (JWT).
• verificationKeyOverride: string
= ''
Overrides the default ES256 JWT verification key loaded from app settings.
Returns
Promise
<AuthTokenClaims
>
Object containing auth token claims.
verifyWebhook()
verifyWebhook(
payload
,headers
,secret
):Promise
<unknown
>
Verifies a webhook request by checking the signature and asserting the timestamp is within 5 minutes of the current time to prevent replay attacks.
Parameters
• payload: Object
The raw JSON payload/body of the webhook request. This must be unaltered or signature verification will fail.
• headers: WebhooksVerificationHeaderInput
A JSON object containing the webhook's ID, timestamp, and signature sent in the headers of the webhook request. This input object must contain id
, timestamp
, and signature
keys.
• secret: string
The webhook secret to use for verifying the webhook request.
Returns
Promise
<unknown
>
verified payload if the webhook signature is valid otherwise throws.