Relationships API

Manage Zanzibar-style relationship tuples.

Relationship tuples power ReBAC (relationship-based access control). Each tuple represents a subject-relation-object triple used in graph traversal during permission checks.

Scope: permissions:manage

Rate limit: 500/hr

List relationships

GET /api/v1/permissions/relationships

Supports filtering by subject, relation, or object.

Parameter	Type	Description
subject	string	Filter by subject (e.g., user:steve)
relation	string	Filter by relation (e.g., owner)
object	string	Filter by object (e.g., folder:design)

curl "https://api.platformxe.com/api/v1/permissions/relationships?subject=user:steve" \
  -H "x-api-key: pxk_live_your_api_key_here"

const rels = await px.permissions.listRelationships({
  subject: 'user:steve',
});

Response

{
  "success": true,
  "data": {
    "relationships": [
      {
        "id": "rel_abc123",
        "subject": "user:steve",
        "relation": "owner",
        "object": "folder:design",
        "createdAt": "2026-04-01T10:00:00.000Z"
      }
    ]
  }
}

Batch write/delete relationships

POST /api/v1/permissions/relationships

Send an array of operations. Each operation is either WRITE (create) or DELETE (remove).

Field	Type	Required	Description
operations	array	Yes	Batch of write/delete operations
operations[].operation	string	Yes	WRITE or DELETE
operations[].subject	string	Yes	Subject identifier (e.g., user:alice)
operations[].relation	string	Yes	Relation type (e.g., member, owner)
operations[].object	string	Yes	Object identifier (e.g., team:engineering)

curl -X POST https://api.platformxe.com/api/v1/permissions/relationships \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "operations": [
      { "operation": "WRITE", "subject": "user:alice", "relation": "member", "object": "team:design" },
      { "operation": "WRITE", "subject": "team:design", "relation": "owner", "object": "project:rebrand" },
      { "operation": "DELETE", "subject": "user:bob", "relation": "member", "object": "team:design" }
    ]
  }'

await px.permissions.writeRelationships({
  operations: [
    { operation: 'WRITE', subject: 'user:alice', relation: 'member', object: 'team:design' },
    { operation: 'WRITE', subject: 'team:design', relation: 'owner', object: 'project:rebrand' },
    { operation: 'DELETE', subject: 'user:bob', relation: 'member', object: 'team:design' },
  ],
});

Error responses

Code	Description
BAD_REQUEST	Missing required fields or invalid operation type
FORBIDDEN	API key missing permissions:manage scope