ReBAC API Calls

Every relationship-based access control (ReBAC) object you create in the Permit.io dashboard can also be created through the Permit API or an SDK. This page is a reference for developers who build a ReBAC policy from code: for each object, it lists the endpoint and an example request with curl and the SDKs. For the concepts behind each object, see What is ReBAC?.

Before you call the API

Item	Value
Base URL	https://api.permit.io
Authentication	Authorization: Bearer <API key> header with an environment API key. See Get your API key.
{proj_id}, {env_id} in paths	The key or ID of your project and environment. See Get the project and environment.
{resource_id}, {role_id} in paths	The key or ID of the resource type and role

The curl examples read three shell variables: $permit_project (project key), $permit_env (environment key), and $permit_sdk_api_key (API key). The SDK examples assume an initialized permit client; see the Node.js SDK quickstart or the Python SDK quickstart.

Each create call returns HTTP 200 with the created object as JSON.

Create a resource role

A resource role is a role defined on one resource type, with the actions it permits on that type.

Endpoint: POST to this URL. See Resource Roles in the API reference.

https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles

This example creates a maintainer role on the repo resource that permits the read and write actions:

cURL

curl https://api.permit.io/v2/schema/$permit_project/$permit_env/resources/repo/roles \
  -X POST \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "maintainer",
    "name": "Maintainer",
    "permissions": ["read", "write"]
  }'

Node.js

await permit.api.resourceRoles.create("repo", {
  key: "maintainer",
  name: "Maintainer",
  permissions: ["read", "write"],
});

Create a resource relation

A resource relation defines how instances of two resource types can relate, for example a folder that is the parent of a file.

Endpoint: POST to this URL, where {resource_id} is the object resource type. See Resource Relations in the API reference.

https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/relations

This example creates a parent relation on the file resource, with folder as the subject resource:

cURL

curl https://api.permit.io/v2/schema/$permit_project/$permit_env/resources/file/relations \
  -X POST \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "parent",
    "name": "Parent",
    "subject_resource": "folder"
  }'

Python

await permit.api.resource_relations.create(
    "file",
    {
        "key": "parent",
        "name": "Parent",
        "subject_resource": "folder",
    }
)

Node.js

await permit.api.resourceRelations.create("file", {
  key: "parent",
  name: "Parent",
  subject_resource: "folder",
});

Create a resource instance

A resource instance is one object of a resource type, in one tenant, such as the file 2023_report. The key, resource, and tenant fields are required.

Endpoint: POST to this URL. See Resource Instances in the API reference.

https://api.permit.io/v2/facts/{proj_id}/{env_id}/resource_instances

This example creates the 2023_report instance of the file resource in the default tenant:

cURL

curl https://api.permit.io/v2/facts/$permit_project/$permit_env/resource_instances \
  -X POST \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "file",
  "key": "2023_report",
  "tenant": "default"
  }'

Node.js

await permit.api.resourceInstances.create({
  resource: "file",
  key: "2023_report",
  tenant: "default",
});

Assign a role to a user on a resource instance

A role assignment gives a user a role. With resource_instance, the role applies to that one instance, in the format resource_type:instance_key. The user and role fields are required.

Endpoint: POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/role_assignments. See Role Assignments in the API reference.

This example gives the user john@acme.com the viewer role on file:2023_report:

cURL

curl https://api.permit.io/v2/facts/$permit_project/$permit_env/role_assignments \
  -X POST \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "john@acme.com",
    "role": "viewer",
    "resource_instance": "file:2023_report"
  }'

Node.js

await permit.api.roleAssignments.assign({
  user: "john@acme.com",
  role: "viewer",
  resource_instance: "file:2023_report",
});

Create a relationship tuple

A relationship tuple connects two resource instances through a relation: the subject instance has the relation to the object instance. Both instances must be in the same tenant. The subject, relation, and object fields are required.

Endpoint: POST to this URL. See Relationship tuples in the API reference.

https://api.permit.io/v2/facts/{proj_id}/{env_id}/relationship_tuples

This example makes the finance folder the parent of the file 2023_report:

cURL

curl https://api.permit.io/v2/facts/$permit_project/$permit_env/relationship_tuples \
  -X POST \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "folder:finance",
  "relation": "parent",
  "object": "file:2023_report"
}'

Node.js

await permit.api.relationshipTuples.create({
  subject: "folder:finance",
  relation: "parent",
  object: "file:2023_report",
});

Create a role derivation

A role derivation grants a role on a resource instance to users who hold a role on a related instance. You can create a role derivation in two ways:

Method	Request	Use it to
Update the resource role	PATCH /v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id} with a granted_to object	Set derivations as part of a role update. The examples below use this method.
Create an implicit grant	POST /v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}/implicit_grants with role, on_resource, and linked_by_relation	Add one derivation to a role. See Implicit Grants in the API reference.

The implicit grants endpoint URL:

https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}/implicit_grants

This example updates the editor role on file so that a user with the editor role on a folder derives the editor role on every file whose parent is that folder:

cURL

curl https://api.permit.io/v2/schema/$permit_project/$permit_env/resources/file/roles/editor \
  -X PATCH \
  -H "Authorization: Bearer $permit_sdk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "granted_to": {
        "users_with_role": [
            {
                "linked_by_relation": "parent",
                "on_resource": "folder",
                "role": "editor"
            }
        ]
	}
  }'

Node.js

await permit.api.resourceRoles.update("file", "editor", {
  granted_to: {
    users_with_role: [
      {
        linked_by_relation: "parent",
        on_resource: "folder",
        role: "editor",
      },
    ],
  },
});

With the relationship tuple from the previous section, a user with the editor role on folder:finance derives the editor role on file:2023_report.

Related pages

• What is ReBAC?
• Groups API
• Check permissions