List resource instances with the Node.js SDK
permit.api.resourceInstances.list() lists the resource instances in the Permit.io environment that your Node.js SDK client is connected to. A resource instance is one object of a resource type, such as the file file:budget-2024 of the file resource. Relationship-based access control (ReBAC) policies grant roles on resource instances. This reference is for backend developers who read resource instances from code.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client.
Method signature
| Method | Signature |
|---|---|
permit.api.resourceInstances.list | list(params?: IListResourceInstanceParams): Promise<ResourceInstanceRead[]> |
Parameters
permit.api.resourceInstances.list() takes one optional object with these fields:
| Field | Type | Required | Description |
|---|---|---|---|
tenant | string | No | Key or ID of the tenant. |
resource | string | No | Key or ID of the resource type. |
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 lists the first 20 instances of the file resource in the default tenant.
await permit.api.resourceInstances.list({
tenant: "default",
resource: "file",
page: 1,
perPage: 20,
});
Return value
The method resolves to an array of ResourceInstanceRead objects, one per instance on the requested page:
| Field | Type | Description |
|---|---|---|
key | string | Key of the instance. Pass the key in the resource of permit.check(). |
resource | string | Key of the resource type. |
tenant | string | Key of the tenant that the instance belongs to. |
attributes | object | Instance attributes. |
id, resource_id, tenant_id | string | IDs of the instance, resource type, and tenant. |
organization_id, project_id, environment_id | string | IDs of the organization, project, and environment. |
created_at, updated_at | string | ISO 8601 timestamps. |
To read every instance, request the next page until the array has fewer items than perPage.
If the Permit API returns an error status code, the method throws a PermitApiError.