Create or import a user

Privy allows you to import a single user into your Privy app. To import a user, pass their linked accounts (wallet, email, etc.) as part of the user creation request. You can also generate a wallet when you create a user.

When an imported user logs in, all of their imported accounts will be included in their user object. If the imported user has a pregenerated embedded wallet, that wallet will be available to the user upon sign in.

Use the PrivyClient’s importUser method to import a single user into your Privy app.

const user = await privy.importUser({
  linkedAccounts: [
    {
      type: 'email',
      address: '[email protected]'
    }
  ],
  wallets: [{chainType: "ethereum"}]
  customMetadata: {
    key: 'value'
  }
});

Parameters

linkedAccounts

LinkedAccount[]

required

An array including all of the user’s linked accounts. These objects are in the same shape as the linked accounts returned by getUser. For each linked account, you must specify the type and must not include a verifiedAt timestamp.

LinkedAccount types

AppleAccount

Field	Type	Description
`type`	`'apple_oauth'`	N/A
`email`	`string`	Email address associated with the user’s Apple account.
`subject`	`number`	ID of user from Apple’s user API.

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. Include the 4-digit discriminator prefixed by ’#’.

(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).

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
`telegramUserId`	`string`	ID of a user’s telegram account.
`firstName`	`string`	The first name displayed on a user’s telegram account.
`lastName`	`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`<br/>`SDK: profilePictureUrl	`string`	(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.

(See Twitter docs)

SmartWalletAccount

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

WalletAccount

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

customMetadata

object

An object containing any custom metadata you want to associate with the user. This metadata will be returned in the user object when the user logs in.

wallets

WalletCreateRequestType[]

(Optional) An array of wallets to create for the user.

Hide child attributes

chainType

'ethereum' | 'solana' | 'stellar' | 'cosmos' | 'sui'

required

The chain type of the wallet to create.

additionalSigners

object[]

Hide child attributes

signerId

string

The ID of the signer.

policyIds

string[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

createSmartWallet

boolean

Set to true to create a smart wallet with the user’s wallet as the signer. Can only be set on wallets where chainType is ethereum.

Use the PrivyClient’s importUser method to import a single user into your Privy app.

const user = await privy.importUser({
  linkedAccounts: [
    {
      type: 'email',
      address: '[email protected]'
    }
  ],
  wallets: [{chainType: "ethereum"}]
  customMetadata: {
    key: 'value'
  }
});

Parameters

linkedAccounts

LinkedAccount[]

required

LinkedAccount types

AppleAccount

Field	Type	Description
`type`	`'apple_oauth'`	N/A
`email`	`string`	Email address associated with the user’s Apple account.
`subject`	`number`	ID of user from Apple’s user API.

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. Include the 4-digit discriminator prefixed by ’#’.

(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).

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
`telegramUserId`	`string`	ID of a user’s telegram account.
`firstName`	`string`	The first name displayed on a user’s telegram account.
`lastName`	`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`<br/>`SDK: profilePictureUrl	`string`	(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.

(See Twitter docs)

SmartWalletAccount

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

WalletAccount

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

customMetadata

object

An object containing any custom metadata you want to associate with the user. This metadata will be returned in the user object when the user logs in.

wallets

WalletCreateRequestType[]

(Optional) An array of wallets to create for the user.

Hide child attributes

chainType

'ethereum' | 'solana' | 'stellar' | 'cosmos' | 'sui'

required

The chain type of the wallet to create.

additionalSigners

object[]

Hide child attributes

signerId

string

The ID of the signer.

policyIds

string[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

createSmartWallet

boolean

Set to true to create a smart wallet with the user’s wallet as the signer. Can only be set on wallets where chainType is ethereum.

Make a POST request to:

https://auth.privy.io/api/v1/users

Below is a sample cURL command for importing a new user into Privy:

$ curl --request POST https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "linked_accounts": [
    {
      "address": "[email protected]",
      "type": "email"
    }
  ]
}'

Parameters

linked_accounts

LinkedAccount[]

required

custom_metadata

object

An object containing any custom metadata you want to associate with the user. This metadata will be returned in the user object when the user logs in.

wallets

WalletCreateRequestType[]

(Optional) An array of wallets to create for the user.

Hide child attributes

chainType

'ethereum' | 'solana' | 'stellar' | 'cosmos' | 'sui'

required

The chain type of the wallet to create.

additional_signers

object[]

Hide child attributes

signerId

string

The ID of the signer.

policy_ids

string[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

create_smart_wallet

boolean

Set to true to create a smart wallet with the user’s wallet as the signer. Can only be set on wallets where chainType is ethereum.

A successful response will include the new user object along with their DID:

{
  "id": "did:privy:clddy332f002tyqpq3b3lv327",
  "created_at": 1674788927,
  "linked_accounts": [
    {
      "address": "[email protected]",
      "type": "email",
      "verified_at": 1674788927
    }
  ]
}

User import endpoints have a rate limit of 240 users in total per minute. If you are being rate limited, responses will have status code 429. We suggest you set up exponential back-offs starting at 1 second to seamlessly recover.

Migrating users to Privy

Users

Managing users

Webhooks

Create or import a user

Parameters

Parameters

Parameters

Migrating users to Privy

Users

Managing users

Webhooks

​Parameters

​Parameters

​Parameters

Parameters

Parameters

Parameters