Appearance
Importing a single user
Privy allows you to import a single user into your Privy app. If you'd prefer, you can also import users in bulk.
Using @privy-io/server-auth
Use the PrivyClient
's importUser
method to import a single user into your Privy app.
tsx
const user = await privy.importUser({
linkedAccounts: [
{
type: 'email',
address: '[email protected]',
},
],
createEmbeddedWallet: true,
});
As a parameter to the method, pass an ImportUserInput
object with the following fields:
Field | Type | Description |
---|---|---|
linkedAccounts | LinkedAccount[] | 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. |
createEmbeddedWallet | boolean | (Optional) Whether to pregenerate an embedded wallet for the imported user. Defaults to false . |
Using the REST API
Make a POST
request to:
sh
https://auth.privy.io/api/v1/users
In the body of the request, include the following fields:
linked_accounts
: (required) a list ofLinkedAccount
objects. See the types for this object below.create_embedded_wallet
: (optional) a boolean indicating whether to pregenerate an embedded wallet for this user. Defaults tofalse
.
INFO
User import endpoints have heavier 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.
See the types for LinkedAccount
objects
Note:
- Each account should be a JSON object including all the necessary fields for that account
type
. Valid accounttype
s are'wallet'
,'email'
,'phone'
,'discord_oauth'
,'github_oauth'
,'twitter_oauth'
,'google_oauth'
,'linkedin_oauth'
,'farcaster'
, and'custom_jwt'
. See below for what additional information for each accounttype
. Please exclude theverifiedAt
field. - If importing a user with a
custom_jwt
account, thecustom_jwt
account must be the only element of thelinked_accounts
array. It is not permitted to import a user with acustom_jwt
account and otherlinked_accounts
.
EmailAccount
extends LinkedAccount
Field | Type | Description |
---|---|---|
type | 'email' | N/A |
address | string | Email address of user account. |
PhoneAccount
extends LinkedAccount
Field | Type | Description |
---|---|---|
type | 'email' | N/A |
number | true | Phone number of user account (non-international numbers default to US). |
WalletAccount
extends LinkedAccount
Field | Type | Description |
---|---|---|
type | 'wallet' | N/A |
chain_type | 'ethereum' | Type of chain for the wallet. Only EVM chains ('ethereum' ) are currently supported. |
address | string | Checksummed wallet address. |
GoogleAccount
extends LinkedAccount
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. |
GithubAccount
extends LinkedAccount
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)
DiscordAccount
extends LinkedAccount
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)
TwitterAccount
extends LinkedAccount
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 '@'. |
(See Twitter docs)
LinkedinAccount
extends LinkedAccount
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)
SpotifyAccount
extends LinkedAccount
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)
CustomJwtAccount
extends LinkedAccount
Field | Type | Description |
---|---|---|
type | 'custom_jwt' | N/A |
custom_id | string | ID of user from Twitter user API response. |
Below is a sample cURL command for importing a new user into Privy:
bash
$ 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>" \
-d '{
"linked_accounts": [
{
"subject": "1234567890",
"username": "batman#1234",
"email": "[email protected]",
"type": "discord_oauth"
},
{
"number": "+1 123 456 7890",
"type": "phone"
},
{
"subject": "1234567890",
"email": "[email protected]",
"name": "Bruce Wayne",
"type": "google_oauth"
},
{
"address": "[email protected]",
"type": "email"
},
{
"address": "0x3DAF84b3f09A0E2092302F7560888dBc0952b7B7",
"type": "wallet",
"chain_type": "ethereum" # "ethereum" is the only valid value for chain_type
},
{
"subject": "1234567890",
"username": "batman",
"name": "Batman",
"type": "twitter_oauth"
},
{
"subject": "1234567890",
"username": "joker",
"name": "Joker",
"type": "github_oauth",
}
]
}'
A successful response will include the new user object along with their DID, like below. Once a user has been imported into Privy, if they log in, all of their imported accounts (wallet, email, etc.) 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.
Below is a sample successful response for importing a new user into Privy:
json
{
"id": "did:privy:clddy332f002tyqpq3b3lv327",
"created_at": 1674788927,
"linked_accounts": [
{
"subject": "1234567890",
"username": "batman#1234",
"email": "[email protected]",
"type": "discord_oauth",
"verified_at": 1674788927
},
...
{
"subject": "1234567890",
"username": "joker",
"name": "Joker",
"type": "github_oauth",
"verified_at": 1674788927
}
]
}