Get the roles assigned to a user with the Node.js SDK
permit.api.users.getAssignedRoles() lists the role assignments of a user in the Permit.io environment that your Node.js SDK client is connected to. Filter by tenant to get the roles of the user in one tenant, or omit the tenant to get the roles of the user in every tenant. This reference is for backend developers who read role assignments from code.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client.
Method signature
| Method | Signature | Status |
|---|---|---|
permit.api.users.getAssignedRoles | getAssignedRoles(params: IGetUserRoles): Promise<RoleAssignmentRead[]> | Recommended |
permit.api.getAssignedRoles | getAssignedRoles(user: string, tenant?: string): Promise<RoleAssignmentRead[]> | Deprecated alias with positional arguments |
Parameters
permit.api.users.getAssignedRoles() takes one object with these fields:
| Field | Type | Required | Description |
|---|---|---|---|
user | string | Yes | Key or ID of the user. |
tenant | string | No | Key or ID of the tenant. If you omit tenant, the method returns the role assignments of the user in all tenants. |
detailed | boolean | No | If true, each assignment includes full details about the user, tenant, and role. Defaults to false. |
includeTotalCount | boolean | No | If true, the method returns a paginated result with a total count. Defaults to false. |
page | number | No | Page number of the results, starting at 1. Defaults to 1. |
perPage | number | No | Number of results per page, up to 100. Defaults to 100. |
The deprecated permit.api.getAssignedRoles(user, tenant) takes the user key or ID and an optional tenant key or ID as positional arguments. It sends no page size, so the Permit API returns only the first page of results at the API default page size.
Parameter object for the recommended method:
{
user: "userId",
tenant: "tenantId"
}
Example
const roles = await permit.api.users.getAssignedRoles({ user: userKey, tenant: tenantKey });
Return value
The method resolves to an array of RoleAssignmentRead objects. Each object has id, user, role, tenant, resource_instance (for instance-level roles), user_id, role_id, tenant_id, and created_at.
With detailed: true, the array holds detailed role assignment objects. With includeTotalCount: true, the method resolves to an object with data (the assignments), total_count, and page_count.
If the Permit API returns an error status code, permit.api.users.getAssignedRoles() throws a PermitApiError.