Appearance
Querying multiple users
Privy also allows you to query all of your users and their linked accounts.
WARNING
Privy rate limits REST API endpoints that you may call from your server. If you suspect your team will require an increased rate limit, please reach out to support!
Using @privy-io/server-auth
Use the PrivyClient
's getUsers
method to get a list of all of your users. Do not pass any parameters to the method.
ts
const users = await privy.getUsers();
This method will return an array of User
objects. This method automatically handles the pagination of the Privy API, and the array will include all of your users.
Using the REST API
Make a GET
request to:
sh
https://auth.privy.io/api/v1/users
You should specify the app ID you are querying in your request headers.
This is a paginated query, and the API will return up to 100 users for a single request.
Parameters
In the request query parameters, specify the following fields:
cursor
(optional)- When you request a batch of users from Privy, the API will return a cursor for the next batch of users in the
next_cursor
field of the response. This will be a Privy DID (e.g. 'did:privy:123456'). - If you are requesting the first batch of users for your app, do not include a
cursor
in your request parameters. - If you have already requested a batch of users and want to request the next batch, set the
cursor
in your request parameters to be thenext_cursor
returned by the API in your previous query. If the providedcursor
is not a valid Privy DID, the API will return an error.
- When you request a batch of users from Privy, the API will return a cursor for the next batch of users in the
limit
(optional): The number of users you would like the API to return. Defaults to and may not exceed 100.
As an example, to get the first 100 users for your app, you should include no URL query parameters:
sh
curl --request GET https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"
Then, to get the next 100 users for your app, you should pass the next_cursor
field of the last response as the cursor
in your request query parameters:
sh
# Replace 'did:privy:123456' below with the `next_cursor` returned by the last query
curl --request GET https://auth.privy.io/api/v1/users?cursor=did:privy:123456 \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"
Response
A successful response will include:
data
: the user objects for your users as an arraynext_cursor
: the cursor to be used in your next request to this API
Below is an example:
json
{
"data": [
{
"id": "did:privy:cfbsvtqo2c22202mo08847jdux2z",
"created_at": 1667165891,
"linked_accounts": [
{
"type": "wallet",
"address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328",
"chain_type": "ethereum",
"verified_at": 1667165891
},
{
"type": "email",
"address": "[email protected]",
"verified_at": 1667350653
}
]
}
],
"next_cursor": "did:privy:123456789"
}
Getting all users
To get all of the users for your app, you should iteratively request this API, and with each request, increment the cursor to be the next_cursor
returned by the previous query. When there are no more results to return, the API response will return an empty array of users in the data
field and the next_cursor
field will be null
.
Below are JavaScript and Python examples for getting all your users:
jsx
// Helper function to query Privy's API
const fetchPageOfUsers = async (cursor?: string) => {
// Specify cursor in URL params if a cursor is provided
const url = 'https://auth.privy.io/api/v1/users' + (cursor ? `?cursor=${cursor}` : '');
const response = await fetch(url, {
method: 'GET',
headers: {
Authorization: `Basic ${btoa(`${'your-privy-app-id'}:${'your-privy-app-secret'}`)}`,
'privy-app-id': 'your-privy-app-id',
},
});
return response.json();
};
// Iteratively requesting all users
let cursor;
let query;
let users = [];
// This loop will terminate after there are no more users to request,
// which occurs when the `next_cursor` is null.
do {
query = await fetchPageOfUsers(cursor);
users = users.concat(query.data);
cursor = query.next_cursor;
} while (cursor !== null);