Permissions

Permission management endpoints.

Base path: /api/v1/permissions

Naming Convention

Permissions follow a resource:action naming pattern:

users:read
users:create
users:update
users:delete
users:assign_roles
roles:read
roles:create
roles:update
roles:delete
permissions:read
permissions:create
permissions:update
permissions:delete

---

List Permissions

GET /api/v1/permissions

Required permission: permissions:read

Query parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	20	Items per page
name	string	—	Filter by name (case-insensitive)
description	string	—	Filter by description (case-insensitive)
role_ids	string	—	Filter by role ids

Response 200 OK

{
  "data": [
    {
      "id": "uuid",
      "name": "users:read",
      "description": "View users",
      "roles": [
        {
          "id": "uuid",
          "name": "admin",
          "description": "Full access to everything"
        }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

---

Create Permission

POST /api/v1/permissions

Required permission: permissions:create

Request body

{
  "name": "reports:read",
  "description": "View reports"
}

Field	Type	Required	Constraints
name	string	✅	3–100 characters
description	string	❌	Max 255 characters

Response 201 Created — full PermissionResponse object.

Errors

Status	Description
409	Permission name already exists

---

Get Permission

GET /api/v1/permissions/{id}

Required permission: permissions:read

Response 200 OK — full PermissionResponse object.

Errors

Status	Description
404	Permission not found

---

Update Permission

Only description and role assignments can be updated. Permission name is immutable after creation.

PATCH /api/v1/permissions/{id}

Required permission: permissions:update

Request body — all fields optional

{
  "description": "Updated description",
  "role_ids": ["uuid-1", "uuid-2"]
}

Field	Type	Required	Constraints
description	string	❌	Max 255 characters
role_ids	UUID array	❌	Must exist in DB

Response 200 OK — updated PermissionResponse object.

Warning

If role_ids is provided, it replaces all existing role assignments. To keep existing roles, include their IDs in the request. Sending an empty array [] removes all role assignments.

Errors

Status	Description
400	One or more roles not found
404	Permission not found

---

Delete Permission

Soft-deletes a permission. Existing role assignments are not affected immediately but the permission will be excluded from future token generation.

DELETE /api/v1/permissions/{id}

Required permission: permissions:delete

Response 204 No Content

Errors

Status	Description
404	Permission not found