Roles & Permissions API

Manage RBAC roles, permissions, and user-role assignments.

Roles

Base path: /api/admin/applications/:appId/roles

Create Role

POST /api/admin/applications/:appId/roles

Field	Type	Required	Description
name	string	✅	Role name
description	string		Role description

{
  "name": "Sales Manager",
  "description": "Full access to the sales pipeline"
}

Response: 201 Created — Role object with auto-generated slug.

List Roles

GET /api/admin/applications/:appId/roles

Response: 200 OK — All roles for the application.

Get Role

GET /api/admin/applications/:appId/roles/:roleId

Response: 200 OK — Role with its assigned permissions.

Update Role

PUT /api/admin/applications/:appId/roles/:roleId

Field	Type	Description
name	string	Role name
description	string	Role description

Archive Role

POST /api/admin/applications/:appId/roles/:roleId/archive

WARNING

System roles (is_system = true) cannot be archived.

Assign Permission to Role

POST /api/admin/applications/:appId/roles/:roleId/permissions

Field	Type	Required	Description
permissionId	uuid	✅	Permission to assign

Remove Permission from Role

DELETE /api/admin/applications/:appId/roles/:roleId/permissions/:permissionId

---

Permissions

Base path: /api/admin/applications/:appId/permissions

Create Permission

POST /api/admin/applications/:appId/permissions

Field	Type	Required	Description
name	string	✅	Permission name (e.g., deals:write)
description	string		Permission description

List Permissions

GET /api/admin/applications/:appId/permissions

Get Permission

GET /api/admin/applications/:appId/permissions/:permissionId

Archive Permission

POST /api/admin/applications/:appId/permissions/:permissionId/archive

---

User-Role Assignments

Base path: /api/admin/organizations/:orgId/users/:userId/roles

Assign Role to User

POST /api/admin/organizations/:orgId/users/:userId/roles

Field	Type	Required	Description
roleId	uuid	✅	Role to assign

Remove Role from User

DELETE /api/admin/organizations/:orgId/users/:userId/roles/:roleId

List User's Roles

GET /api/admin/organizations/:orgId/users/:userId/roles

Response: 200 OK — All roles assigned to the user, grouped by application.