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.

Pipeline Authoring Note

Permission rules are one layer of Pipeline Authoring authority. Workspace grants, repository and connector permissions, the immutable runtime permission profile, and exact effect approvals are evaluated separately; a rule cannot turn one approval type into another or expand the runtime profile. See Authoring Workspace Access and Authoring API Egress.