Roles & Permissions API

Role-based access control with system roles and custom role support. Forgexa has roles at two levels: organization and workspace.

Organization Roles

Role	Description
owner	Full control including ownership transfer and deletion. One per org.
admin	Manage members, invitations, integrations, budgets, audit logs, templates.
member	View org data, access workspaces, create workspaces.

Organization admins automatically have admin-level access to all workspaces within the organization.

Workspace Roles (System)

Role	Description
owner	Full control including ownership transfer
admin	Workspace/project management, member management
developer	Create/execute work items, review gates
viewer	Read-only access

Permission Matrix

Get the full permission matrix for all system roles.

GET /api/v1/permissions/matrix
Authorization: Bearer <token>

Response 200 OK

{
  "permissions": [
    "project:read",
    "project:create",
    "requirement:read",
    "execution:execute",
    "gate:review",
    "deployment:trigger"
  ],
  "descriptions": {
    "project:read": "View projects and their settings",
    "execution:execute": "Start new execution pipelines",
    "gate:review": "Submit gate reviews (approve/reject)"
  },
  "roles": {
    "viewer": ["project:read", "requirement:read", "execution:read"],
    "developer": ["project:read", "requirement:create", "execution:execute", "gate:review"],
    "admin": ["project:create", "project:update", "deployment:trigger"],
    "owner": ["project:delete", "workspace:settings"]
  }
}

Custom Roles

List Roles

Returns both system roles and workspace-scoped custom roles.

GET /api/v1/workspaces/{workspace_id}/roles
Authorization: Bearer <token>

Create Custom Role

Requires admin role.

POST /api/v1/workspaces/{workspace_id}/roles
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "QA Lead",
  "description": "Can review gates and manage QA suites",
  "permissions": [
    "project:read",
    "requirement:read",
    "execution:read",
    "gate:read",
    "gate:review",
    "qa:read",
    "qa:execute",
    "qa:manage"
  ]
}

Update Custom Role

PUT /api/v1/workspaces/{workspace_id}/roles/{role_id}
Authorization: Bearer <token>

System roles cannot be modified.

Delete Custom Role

DELETE /api/v1/workspaces/{workspace_id}/roles/{role_id}
Authorization: Bearer <token>

System roles cannot be deleted.