ReBAC (Relationship-Based Access Control)

Overview

The ReBAC (Relationship-Based Access Control) API provides endpoints for implementing relationship-based access control inspired by Google Zanzibar. Define relationships between objects and evaluate permissions based on those relationships.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/rebac/relation-definitions	List relation definitions
POST	/api/admin/rebac/relation-definitions	Create relation definition
PUT	/api/admin/rebac/relation-definitions/:id	Update relation definition
DELETE	/api/admin/rebac/relation-definitions/:id	Delete relation definition
GET	/api/admin/rebac/tuples	List relationship tuples
POST	/api/admin/rebac/tuples	Create relationship tuple
DELETE	/api/admin/rebac/tuples	Delete relationship tuple
POST	/api/admin/rebac/check	Check permission
POST	/api/admin/rebac/expand	Expand relations

---

Zanzibar DSL

Authrim supports a Google Zanzibar-style relation definition language.

Basic Syntax

definition <object_type> {
  relation <relation_name>: [<subject_type>]
  permission <permission_name> = <relation> | <expression>
}

Example: Document Sharing

definition user {}

definition group {
  relation member: [user]
}

definition document {
  relation owner: [user]
  relation editor: [user, group#member]
  relation viewer: [user, group#member]

  permission edit = owner | editor
  permission view = edit | viewer
}

---

List Relation Definitions

Retrieve relation definitions for the tenant.

Endpoint

GET /api/admin/rebac/relation-definitions

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 50)
cursor	string	-	Pagination cursor
object_type	string	-	Filter by object type

Request Example

curl -X GET "https://{tenant-domain}/api/admin/rebac/relation-definitions" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "reldef_doc",
      "object_type": "document",
      "relations": [
        {
          "name": "owner",
          "subject_types": ["user"]
        },
        {
          "name": "editor",
          "subject_types": ["user", "group#member"]
        },
        {
          "name": "viewer",
          "subject_types": ["user", "group#member"]
        }
      ],
      "permissions": [
        {
          "name": "edit",
          "expression": "owner | editor"
        },
        {
          "name": "view",
          "expression": "edit | viewer"
        }
      ],
      "created_at": 1705881600,
      "updated_at": 1705968000
    }
  ],
  "total": 5
}

---

Create Relation Definition

Create a new relation definition.

Endpoint

POST /api/admin/rebac/relation-definitions

Request Body

Field	Type	Required	Description
object_type	string	✓	Object type
dsl	string	✓	Definition in Zanzibar DSL format

Request Example

curl -X POST "https://{tenant-domain}/api/admin/rebac/relation-definitions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "folder",
    "dsl": "definition folder {\n  relation owner: [user]\n  relation parent: [folder]\n  relation viewer: [user, group#member]\n  \n  permission view = owner | viewer | parent->view\n  permission edit = owner | parent->edit\n}"
  }'

Response Example

{
  "id": "reldef_folder",
  "object_type": "folder",
  "relations": [
    {
      "name": "owner",
      "subject_types": ["user"]
    },
    {
      "name": "parent",
      "subject_types": ["folder"]
    },
    {
      "name": "viewer",
      "subject_types": ["user", "group#member"]
    }
  ],
  "permissions": [
    {
      "name": "view",
      "expression": "owner | viewer | parent->view"
    },
    {
      "name": "edit",
      "expression": "owner | parent->edit"
    }
  ],
  "created_at": 1706140800
}

---

Update Relation Definition

Update an existing relation definition.

Endpoint

PUT /api/admin/rebac/relation-definitions/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/rebac/relation-definitions/reldef_doc" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "definition document {\n  relation owner: [user]\n  relation editor: [user, group#member]\n  relation viewer: [user, group#member]\n  relation commenter: [user]\n  \n  permission edit = owner | editor\n  permission comment = edit | commenter\n  permission view = comment | viewer\n}"
  }'

---

Delete Relation Definition

Delete a relation definition.

Endpoint

DELETE /api/admin/rebac/relation-definitions/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/rebac/relation-definitions/reldef_doc" \
  -H "Authorization: Bearer {token}"

Impact of Deletion

Deleting a relation definition also deletes all tuples associated with that definition.

---

List Relationship Tuples

Retrieve relationship tuples (actual relationships between objects and subjects).

Endpoint

GET /api/admin/rebac/tuples

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 50)
cursor	string	-	Pagination cursor
object_type	string	-	Object type
object_id	string	-	Object ID
relation	string	-	Relation name
subject_type	string	-	Subject type
subject_id	string	-	Subject ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/rebac/tuples?object_type=document&object_id=doc_123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "tuple_abc123",
      "object_type": "document",
      "object_id": "doc_123",
      "relation": "owner",
      "subject_type": "user",
      "subject_id": "usr_owner001",
      "created_at": 1705881600
    },
    {
      "id": "tuple_def456",
      "object_type": "document",
      "object_id": "doc_123",
      "relation": "editor",
      "subject_type": "group",
      "subject_id": "grp_editors",
      "subject_relation": "member",
      "created_at": 1705968000
    }
  ],
  "total": 5,
  "cursor": null
}

---

Create Relationship Tuple

Create a new relationship tuple.

Endpoint

POST /api/admin/rebac/tuples

Request Body

Field	Type	Required	Description
object_type	string	✓	Object type
object_id	string	✓	Object ID
relation	string	✓	Relation name
subject_type	string	✓	Subject type
subject_id	string	✓	Subject ID
subject_relation	string	-	Subject relation (for group members, etc.)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/rebac/tuples" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "document",
    "object_id": "doc_456",
    "relation": "viewer",
    "subject_type": "user",
    "subject_id": "usr_viewer001"
  }'

Response Example

{
  "id": "tuple_xyz789",
  "object_type": "document",
  "object_id": "doc_456",
  "relation": "viewer",
  "subject_type": "user",
  "subject_id": "usr_viewer001",
  "created_at": 1706140800
}

---

Delete Relationship Tuple

Delete a relationship tuple.

Endpoint

DELETE /api/admin/rebac/tuples

Request Body

Field	Type	Required	Description
object_type	string	✓	Object type
object_id	string	✓	Object ID
relation	string	✓	Relation name
subject_type	string	✓	Subject type
subject_id	string	✓	Subject ID

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/rebac/tuples" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "document",
    "object_id": "doc_456",
    "relation": "viewer",
    "subject_type": "user",
    "subject_id": "usr_viewer001"
  }'

---

Check Permission

Check if a user has permission on a specific object.

Endpoint

POST /api/admin/rebac/check

Request Body

Field	Type	Required	Description
object_type	string	✓	Object type
object_id	string	✓	Object ID
permission	string	✓	Permission name
subject_type	string	✓	Subject type
subject_id	string	✓	Subject ID

Request Example

curl -X POST "https://{tenant-domain}/api/admin/rebac/check" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "document",
    "object_id": "doc_123",
    "permission": "edit",
    "subject_type": "user",
    "subject_id": "usr_abc123"
  }'

Response Example

{
  "allowed": true,
  "resolution_path": [
    {
      "relation": "editor",
      "subject": "group:grp_editors#member"
    },
    {
      "relation": "member",
      "subject": "user:usr_abc123"
    }
  ]
}

---

Expand Relations

Expand all subjects that have permission on a specific object and permission.

Endpoint

POST /api/admin/rebac/expand

Request Body

Field	Type	Required	Description
object_type	string	✓	Object type
object_id	string	✓	Object ID
permission	string	✓	Permission name
max_depth	integer	-	Maximum expansion depth (default: 10)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/rebac/expand" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "document",
    "object_id": "doc_123",
    "permission": "view"
  }'

Response Example

{
  "object_type": "document",
  "object_id": "doc_123",
  "permission": "view",
  "subjects": [
    {
      "type": "user",
      "id": "usr_owner001",
      "via": ["owner", "edit", "view"]
    },
    {
      "type": "user",
      "id": "usr_editor001",
      "via": ["editor", "edit", "view"]
    },
    {
      "type": "user",
      "id": "usr_viewer001",
      "via": ["viewer", "view"]
    },
    {
      "type": "user",
      "id": "usr_abc123",
      "via": ["group:grp_editors#member", "editor", "edit", "view"]
    }
  ]
}