Skip to main content

Filter relationship tuples with the API

List the relationship tuples of an environment and filter them by subject, object, relation, resource type, or tenant with the List Relationship Tuples API. This page is for developers who inspect or debug relationship-based access control (ReBAC) data from scripts.

A relationship tuple connects two resource instances with a relation. For example, the tuple Folder:documents parent File:my_pdf says the documents folder is the parent of the my_pdf file. For the concept, see ReBAC overview.

Prerequisites​

In each request on this page, replace:

PlaceholderValue
{project_id}Your project ID or key
{env_id}Your environment ID or key
API_SECRET_KEYYour environment API key

List all relationship tuples​

Send a GET request to /v2/facts/{project_id}/{env_id}/relationship_tuples. Use page (starting at 1) and per_page (up to 100) to page through the results.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

The API responds with an array of relationship tuple objects:

[
    {
        "subject": "Folder:documents",
        "relation": "parent",
        "object": "File:my_pdf",
        "id": "c76f9a129dbe44f88664b7333fef0cce",
        "tenant": "default",
        "subject_id": "6e6855d2b2cf438c9bf79136ec72c188",
        "relation_id": "9c6aee683f5c482cabd2d536734801c9",
        "object_id": "3bdd97e40010426bbf0648d962779122",
        "tenant_id": "f9bcad6ad2a54113ba4f45fc014d4bb0",
        "organization_id": "78f198a252c04572b098cf3aa70f8520",
        "project_id": "1bbb39e66e614bbc831346bb1c15babb",
        "environment_id": "6175ea4cb70b4d08add43ebfa6a30004",
        "created_at": "2023-11-16T08:30:46+00:00",
        "updated_at": "2023-11-16T08:30:46+00:00",
        "subject_details": {
            "key": "documents",
            "tenant": "default",
            "resource": "Folder",
            "attributes": {}
        },
        "relation_details": {
            "key": "parent",
            "name": "parent",
            "description": "Relation expresses possible 'parent' relation between subject of type 'Folder' to object of type 'File'"
        },
        "object_details": {
            "key": "my_pdf",
            "tenant": "default",
            "resource": "File",
            "attributes": {}
        },
        "tenant_details": {
            "key": "default",
            "name": "Default Tenant",
            "description": null,
            "attributes": null
        }
    }
]

Filter parameters​

Add filter query parameters to the list request. When you pass several filters, the API returns only the tuples that match all of the filters (a logical AND).

Query parameterAccepted valuesExample
subjectResource instance ID, or resource_type:resource_instanceFolder:documents
objectResource instance ID, or resource_type:resource_instanceFile:my_pdf
relationRelation ID or keyparent
object_typeResource type ID or keyFile
subject_typeResource type ID or keyFolder
tenantTenant ID or keydefault
detailedtrue returns the full subject and object resource instancestrue

Filter by subject​

The following request returns the tuples whose subject is the Folder:documents resource instance:

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?subject=Folder:documents&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Filter by object​

The following request returns the tuples whose object is the File:my_pdf resource instance:

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?object=File:my_pdf&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Filter by relation​

The following request returns the tuples with the parent relation. You can pass the relation ID, such as 9c6aee683f5c482cabd2d536734801c9, instead of the key.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?relation=parent&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Filter by object type​

The following request returns the tuples whose object is a File resource instance. You can pass the resource ID instead of the key.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?object_type=File&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Filter by subject type​

The following request returns the tuples whose subject is a Folder resource instance. You can pass the resource ID instead of the key.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?subject_type=Folder&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Filter by tenant​

The following request returns the tuples in the default tenant:

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/relationship_tuples?tenant=default&page=1&per_page=10' \
  -H 'authorization: Bearer API_SECRET_KEY'

Verify the filter​

Each tuple in a filtered response matches every filter you passed. For example, with subject=Folder:documents, every tuple has "subject": "Folder:documents". An empty array means no tuple matches all of the filters.

Contents

Edit this page

Need help?