Admin: Permissions

Manage individual permission overrides on users — granting or revoking specific capabilities without changing a user's role.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/permissions	admin:permissions:view	List all permissions
PATCH	/api/permissions/:id	admin:permissions:edit	Update permission metadata
GET	/api/permissions/users/:userId	admin:permissions:view	Get permissions for user
POST	/api/permissions/users/:userId	admin:user_permissions:manage	Add permission override to user
PATCH	/api/permissions/users/:userId/:permId	admin:user_permissions:manage	Update user permission scope
DELETE	/api/permissions/users/:userId/:permId	admin:user_permissions:manage	Remove user permission override

Endpoints

List all permissions

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

Returns every permission defined in the system.

Response — 200

[
  {
    "id": "perm-uuid-001",
    "name": "episode:create",
    "description": "Create new episodes",
    "category": "episodes",
    "scopeable": false,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "descriptionI18n": {
      "uk": "Створювати нові епізоди",
      "en": "Create new episodes",
      "es": "Crear nuevos episodios"
    }
  }
]

---

Update permission metadata

PATCH /api/permissions/:id — Auth required, Permission: admin:permissions:edit

Request body (all fields optional)

{
  "description": "Updated description",
  "scopeable": true
}

Response — 200

{
  "id": "perm-uuid-001",
  "name": "episode:create",
  "description": "Updated description",
  "category": "episodes",
  "scopeable": true,
  "createdAt": "2025-01-01T00:00:00.000Z"
}

---

Get permissions for user

GET /api/permissions/users/:userId — Auth required, Permission: admin:permissions:view

Returns all per-user permission overrides (not inherited from role) for the specified user.

Response — 200

[
  {
    "id": "perm-uuid-005",
    "name": "scene:block:frame:generate",
    "description": "Generate start/end frames with AI",
    "category": "scenes",
    "scopeable": false,
    "scope": "global"
  }
]

---

Add permission override to user

POST /api/permissions/users/:userId — Auth required, Permission: admin:user_permissions:manage

Request body

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

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

Response — 204

---

Update user permission override scope

PATCH /api/permissions/users/:userId/:permId — Auth required, Permission: admin:user_permissions:manage

Request body

{ "scope": "assigned" }

scope must be "global" or "assigned".

Response — 204

---

Remove user permission override

DELETE /api/permissions/users/:userId/:permId — Auth required, Permission: admin:user_permissions:manage

Response — 204