Admin: Roles

Create and manage roles. A role is a named set of permissions that can be assigned to users.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/roles	admin:roles:view	List all roles
GET	/api/roles/:id	admin:roles:view	Get role by ID
POST	/api/roles	admin:roles:create	Create a role
PUT	/api/roles/:id	admin:roles:edit	Update a role
DELETE	/api/roles/:id	admin:roles:delete	Delete a role
POST	/api/roles/:id/permissions	admin:role_permissions:manage	Assign permission to role
PATCH	/api/roles/:id/permissions/:permId	admin:role_permissions:manage	Update permission scope on role
DELETE	/api/roles/:id/permissions/:permId	admin:role_permissions:manage	Revoke permission from role

Endpoints

List all roles

GET /api/roles — Auth required, Permission: admin:roles:view

Response — 200

[
  {
    "id": "role-uuid-001",
    "name": "Editor",
    "createdAt": "2025-01-05T09:00:00.000Z",
    "nameI18n": { "uk": "Редактор", "en": "Editor", "es": "Editor" },
    "permissions": [
      {
        "id": "perm-uuid-001",
        "name": "episode:edit",
        "description": "Edit episodes",
        "category": "episodes",
        "scopeable": false,
        "scope": "global"
      }
    ]
  }
]

---

Get role by ID

GET /api/roles/:id — Auth required, Permission: admin:roles:view

Response — 200 — single role object (same shape as list item, always includes permissions)

---

Create role

POST /api/roles — Auth required, Permission: admin:roles:create

Request body

{ "name": "Narrator" }

Response — 201

{
  "id": "role-uuid-002",
  "name": "Narrator",
  "createdAt": "2025-04-01T10:00:00.000Z",
  "nameI18n": null,
  "permissions": []
}

---

Update role

PUT /api/roles/:id — Auth required, Permission: admin:roles:edit

Request body

{ "name": "Senior Editor" }

Response — 200 — updated role object

---

Delete role

DELETE /api/roles/:id — Auth required, Permission: admin:roles:delete

Response — 204

---

Role Permissions

Assign permission to role

POST /api/roles/:id/permissions — Auth required, Permission: admin:role_permissions:manage

Request body

{
  "permissionId": "perm-uuid-005",
  "scope": "global"
}

Field	Required	Notes
permissionId	yes	UUID of the permission to assign
scope	no	global (default) | assigned

Response — 204

---

Update permission scope on role

PATCH /api/roles/:id/permissions/:permId — Auth required, Permission: admin:role_permissions:manage

Request body

{ "scope": "assigned" }

scope must be "global" or "assigned".

Response — 204

---

Revoke permission from role

DELETE /api/roles/:id/permissions/:permId — Auth required, Permission: admin:role_permissions:manage

Response — 204