List users with the Node.js SDK
permit.api.users.list() lists the users in the Permit.io environment that your Node.js SDK client is connected to. This reference is for backend developers who read or search users from code. To list the users of a single tenant, see List the users of a tenant with the Node.js SDK.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client.
Method signature
| Method | Signature |
|---|---|
permit.api.users.list | list(params?: IUsersListParams): Promise<PaginatedResultUserRead> |
Parameters
permit.api.users.list() takes one optional object with these fields:
| Field | Type | Required | Description |
|---|---|---|---|
search | string | No | Text to match against the user key, email, first name, or last name. |
role | string | No | Key of a role. Returns only users with this role. |
page | number | No | Page number of the results, starting at 1. |
perPage | number | No | Number of results per page, up to 100. If you omit perPage, the Permit API applies its default page size. |
Example
The example fetches the first 20 users who have the admin role and match the search text @permit.io.
await permit.api.users.list({
search: "@permit.io",
role: "admin",
page: 1,
perPage: 20,
});
Return value
The method resolves to a PaginatedResultUserRead object:
| Field | Type | Description |
|---|---|---|
data | UserRead[] | Users on the requested page. Each user has key, id, email, first_name, last_name, attributes, roles, and associated_tenants. |
total_count | number | Number of users that match the filters. |
page_count | number | Number of result pages. |
If the Permit API returns an error status code, the method throws a PermitApiError.