Querying a single user

Privy allows you to get information about a user given their identity token. The response is a User object which includes light weight versions of all the users linked accounts.

To enable identity tokens, visit the dashboard Settings page and toggle on "Return user data in an identity token".

Once you have enabled identity tokens for your application, Privy will automatically include the identity token as a cookie on every request from your frontend to your server.

Then, from your server, you can get the current user's identity token by retrieving the cookie attached to any network request from your front-end application. This identity token can be passed to the getUser function to parse the user details into a typed object.

Example usage of retrieving identity token and passing to getUser from your server in NextJS:

export async function getUserFromRequest(req: NextApiRequest) {
  const idToken = req.cookies.get('privy-id-token');
  try {
    const user = await getUser({idToken: idToken})
    return user;
} catch (error) {
  console.error(error);
}

The method will verfiy that the token is valid and then parse the payload into a lightweight User object. If the identity token cannot be verified, the method will throw an error. If you need the full user object, use the deprecated getUser(privyDID)

TIP

Looking for the types of LinkedAccounts?

See a list of the different account types and the data they include

Note:

• Each account should be a JSON object including all the necessary fields for that account type.
  • Valid account types are apple_oauth, 'custom_auth', 'discord_oauth', 'farcaster', 'github_oauth', 'google_oauth', 'instagram_oauth', 'linkedin_oauth', 'spotify_oauth', 'telegram', 'tiktok_oauth', 'twitter_oauth', 'email', 'phone' and 'wallet'.
• If importing a user with a custom_auth account, the custom_auth account must be the only element of the linked_accounts array. It is not permitted to import a user with a custom_auth account and other linked_accounts.
• You must exclude the verifiedAt field.
• The SDK and REST API have different naming conventions. The SDK uses camelCase and the API uses snake_case.

  CustomJwtAccount

Field	Type	Description
type	'custom_auth'	N/A
API: custom_user_id SDK: customUserId	string	ID of user from custom auth provider.

  DiscordAccount

Field	Type	Description
type	'discord_oauth'	N/A
subject	string	ID of user from Discord user API response.
email	string	Email of user from Discord user API response.
username	string	Username of user from Discord user API response.

(See Discord docs)

  EmailAccount

Field	Type	Description
type	'email'	N/A
address	string	Email address of user account.

  FarcasterAccount

Field	Type	Description
type	'farcaster'	N/A
fid	number	FID of the user from Farcaster user API response.
API: owner_address SDK: ownerAddress	string	Wallet address of the user from Farcaster user API response. Note that this is the Farcaster wallet address, and not the Privy embedded wallet address.
username	string	(Optional) Username of user from Farcaster user API response. Do not include the '@'.
API: display_name SDK: displayName	string	(Optional) Display name of user from Farcaster user API response.
bio	string	(Optional) Bio of user from Farcaster user API response.
API: profile_picture_url SDK: profilePictureUrl	string	(Optional) Profile picture URL of the user from Farcaster user API response. Must be a valid image URL.
API: homepage_url SDK: homepageUrl	string	(Optional) Profile URL of the user from Farcaster user API response.

(See Farcaster docs. Note that the Privy import interface differs slightly from the Farcaster public interface in order to maintain consistency with other Privy LinkedAccount types.)

  GithubAccount

Field	Type	Description
type	'github_oauth'	N/A
subject	string	ID of user from GitHub user API response.
email	string	Email of user from GitHub user API response
name	string	Name of user from GitHub user API response
username	string	Username of user from GitHub user API response

(See GitHub docs)

  GoogleAccount

Field	Type	Description
type	'google_oauth'	N/A
subject	string	sub pulled from Google-provided JWT with "openid" scope.
email	string	email from Google-provided JWT with "email" scope.
name	string	name from Google-provided JWT with "profile" scope.

  InstagramAccount

Field	Type	Description
type	'instagram_oauth'	N/A
subject	string	ID of user from Instagram user API response.
username	string	The name displayed on a user's profile from Instagram's /me API response.

(See Instagram docs)

  LinkedinAccount

Field	Type	Description
type	'linkedin_oauth'	N/A
subject	string	ID of user from LinkedIn user API response.
email	string	Email of user from LinkedIn user API response
name	string	Name of user from LinkedIn user API response. Do not include the '@'.

(See Linkedin docs)

  PhoneAccount

Field	Type	Description
type	'phone'	N/A
number	string	Phone number of user account (non-international numbers default to US).

While number is accepted as input, phoneNumber is returned in the response.

  SmartWalletAccount

Field	Type	Description
type	'smart_wallet'	N/A
address	string	Checksummed smart wallet address.
smart_wallet_type	SmartWalletType	One of 'kernel', 'safe', 'biconomy' or 'light_account'

  SpotifyAccount

Field	Type	Description
type	'spotify_oauth'	N/A
subject	string	ID of user from Spotify user API response.
email	string	Email of user from Spotify user API.
name	string	The name displayed on a user's profile from Spotify display_name API response.

(See Spotify docs)

  TelegramAccount

Field	Type	Description
type	'telegram'	N/A
telegram_user_id	string	ID of a user's telegram account.
first_name	string	The first name displayed on a user's telegram account.
last_name	string	(Optional) The last name displayed on a user's telegram account.
username	string	(Optional) The username displayed on a user's telegram account.
photo_url	string	(Optional) The url of a user's telegram account profile picture.

(See Telegram docs)

  TwitterAccount

Field	Type	Description
type	'twitter_oauth'	N/A
subject	string	ID of user from Twitter user API response.
name	string	Name of user from Twitter user API response
username	string	Username of user from Twitter user API response. Do not include the '@'.
API: profile_picture_url SDK: profilePictureUrl	string	(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.

(See Twitter docs)

  WalletAccount

Field	Type	Description
type	'wallet'	N/A
API: chain_type SDK: chainType	'ethereum'	Type of chain for the wallet. EVM chains ('ethereum') and Solana ('solana') are currently supported.
address	string	Checksummed wallet address.

---

WARNING

Privy has deprecated the preexisting getUser method where Privy DID is passed as the parameter. This legacy method makes an API call to get the full user object and is less efficient than the new implementation, which reconstitutes the User object from the identity token. It is highly recommended to use getUser with the identity token as Privy rate limits REST API endpoints. See the legacy documentation here

INFO

Identity token vs. access token: The identity token includes details about the currently authenticated user, whereas the access token can be used to verify the user's authentication status. The access token should be verified when your backend first receives the request to confirm the request came from an authenticated user, while the identity token can be parsed at any time to get the users details.