Permission Rules API

Manage the platform's declarative permission rules. Rules define which roles can perform which actions on which resources.

Most endpoints require Superadmin access. Space-scoped rules can be created by Space Admins.

Endpoints Overview

Method	Endpoint	Description
GET	/permission-rules	List all rules
POST	/permission-rules	Create a rule
PATCH	/permission-rules/{rule_id}	Update a rule
DELETE	/permission-rules/{rule_id}	Delete a rule
POST	/permission-rules/reset-defaults	Reset to baseline
GET	/permission-rules/resource-types	Get resource type config

---

List Rules

GET /permission-rules

Requires: Superadmin

Query Parameters

Parameter	Type	Default	Description
resource_type	string	—	Filter by resource type
space_id	UUID	—	Filter by space
include_disabled	bool	false	Include disabled rules
skip	integer	0	Pagination offset
limit	integer	50	Page size

Response

{
  "items": [
    {
      "id": "uuid",
      "resource_type": "product",
      "action": "edit",
      "allowed_roles": ["superadmin", "space_admin", "owner"],
      "condition_type": null,
      "priority": 0,
      "description": "Product owners and admins can edit",
      "space_id": null,
      "is_enabled": true,
      "is_baseline": true,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 42
}

Pagination headers (X-Total-Count, X-Page, X-Page-Size) are included in the response.

---

Create Rule

POST /permission-rules

Requires: Superadmin (global rules) or Space Admin (space-scoped rules)

Request Body

{
  "resource_type": "ticket",
  "action": "assign",
  "allowed_roles": ["space_admin", "steward"],
  "condition_type": null,
  "priority": 10,
  "description": "Only stewards and admins can assign tickets",
  "space_id": null,
  "is_enabled": true
}

Fields

Field	Type	Required	Description
resource_type	string	✅	product, comment, ticket, meeting, request
action	string	✅	view, edit, delete, create, approve, assign
allowed_roles	string[]	✅	superadmin, space_admin, member, owner, steward
condition_type	string	—	is_author, is_owner, is_assignee, etc.
priority	integer	—	Higher-priority rules are evaluated first (default: 0)
description	string	—	Human-readable description
space_id	UUID	—	Space scope (null = global)
is_enabled	bool	—	Whether the rule is active (default: true)

---

Update Rule

PATCH /permission-rules/{rule_id}

All fields are optional — only provided fields are updated.

{
  "allowed_roles": ["superadmin", "space_admin"],
  "is_enabled": false
}

---

Delete Rule

DELETE /permission-rules/{rule_id}

Returns 204 No Content. Baseline rules cannot be deleted — returns 400.

---

Reset to Defaults

POST /permission-rules/reset-defaults

Requires: Superadmin

Removes all custom rules and restores the baseline permission set.

{
  "message": "Reset to defaults. 24 baseline rules restored."
}

---

Get Resource Types

GET /permission-rules/resource-types

Requires: Superadmin

Returns the available resource types and their valid actions for use in rule creation UI.