List relationship tuples with the Node.js SDK

permit.api.relationshipTuples.list() lists the relationship tuples in the Permit.io environment that your Node.js SDK client is connected to. A relationship tuple states that a relation, such as parent or owner, exists between a subject resource instance and an object resource instance. Relationship-based access control (ReBAC) policies derive permissions from these tuples. This reference is for backend developers who read the relationship graph from code.

Prerequisites

• A permit client created with an API key for the environment. See Create a Permit client.
• A ReBAC policy with resource relations. See Build ReBAC policies.

Method signature

Method	Signature
permit.api.relationshipTuples.list	list(params: IListRelationshipTuples): Promise<RelationshipTupleRead[]>

Parameters

permit.api.relationshipTuples.list() takes one object. Every field is optional. Pass {} to list tuples without filters.

Field	Type	Required	Description
tenant	string	No	Key or ID of the tenant.
relation	string	No	Key or ID of the relation.
subject	string	No	Subject resource instance, as an ID or in the format resource_type:resource_instance_key.
subjectType	string	No	Key or ID of the subject resource type.
object	string	No	Object resource instance, as an ID or in the format resource_type:resource_instance_key.
objectType	string	No	Key or ID of the object 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.

The SDK always returns an array of tuples without a total count.

Example

The example lists the parent relationship tuples between file:file-1 and folder:folder-1 in the default tenant.

await permit.api.relationshipTuples.list({
  tenant: "default",
  relation: "parent",
  subject: "file:file-1",
  subjectType: "file",
  object: "folder:folder-1",
  objectType: "folder",
  page: 1,
  perPage: 20
});

Return value

The method resolves to an array of RelationshipTupleRead objects:

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "subject": "organization:permitio",
    "relation": "owner",
    "object": "repo:opal",
    "tenant": "default",
    "subject_id": "7c60d51f-b44e-4682-87d6-449835ea4d11",
    "relation_id": "405d8375-3514-403b-8c43-83ae74cfe022",
    "object_id": "12f84e49-af17-4b0c-8cd7-01258769c2ba",
    "tenant_id": "40ef0e48-a11f-4963-a229-e396c9f7e733",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Field	Description
subject, relation, object, tenant	Keys of the subject instance, relation, object instance, and tenant of the tuple.
id	Unique ID of the tuple.
subject_id, relation_id, object_id, tenant_id	IDs of the subject instance, relation, object instance, and tenant.
organization_id, project_id, environment_id	IDs of the organization, project, and environment.
created_at, updated_at	ISO 8601 timestamps.

If the Permit API returns an error status code, the method throws a PermitApiError.

Paginated response of the Permit API

When you call the list relationship tuples API endpoint directly with the include_total_count=true query parameter, the API wraps the tuples in an object with a total count. The Node.js SDK method doesn't return this shape.

{
"data": [
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "subject": "organization:permitio",
    "relation": "owner",
    "object": "repo:opal",
    "tenant": "default",
    "subject_id": "7c60d51f-b44e-4682-87d6-449835ea4d11",
    "relation_id": "405d8375-3514-403b-8c43-83ae74cfe022",
    "object_id": "12f84e49-af17-4b0c-8cd7-01258769c2ba",
    "tenant_id": "40ef0e48-a11f-4963-a229-e396c9f7e733",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
],
"total_count": 1,
"page_count": 1
}

Related pages

• List resource instances with the Node.js SDK
• Build ReBAC policies
• Bulk relationship tuple requests
• List relationship tuples API endpoint