Roles

Role management endpoints for creating, updating, and managing roles with permission assignments. All endpoints require the Super Admin role (or Branch of the Court Clerk, per the route's role list).

The role model

Name
id
Type
string
Description
Unique identifier for the role.
Name
name
Type
string
Description
The name of the role. Must be unique. CMS Admin ships with 10 seeded roles: Super Admin, Counsel, Office of the Court Clerk, Branch of the Court Clerk, Dashboard User, BCC Staff, BCC Evidence, User, Stenographer, Sheriff.
Name
guard_name
Type
string
Description
The guard name for the role (web).
Name
permissions
Type
array<string>
Description
Array of permission names assigned to this role.
Name
description
Type
string | null
Description
Free-text description of the role.
Name
created_at
Type
timestamp
Description
Timestamp when the role was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the role was last updated.

GET/api/roles-list

List all roles

Retrieve a paginated list of roles (50 per page), filterable by name.

Optional attributes

Name
search
Type
string
Description
Search roles by name (case-insensitive partial match).
Name
page
Type
integer
Description
Page number for pagination (default: 1).

Request

GET

/api/roles-list

curl -G https://your-domain.com/api/roles-list \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {token}" \
  --cookie "cms_admin_session={session}" \
  --data-urlencode "search=Sheriff"

Response

{
  "data": [
    {
      "id": "9d8c7b6a-5f4e-3d2c-9d8c-7b6a5f4e3d2c",
      "name": "Sheriff",
      "permissions": ["View Evidence", "View Case Details", "View Case Activities", "View Case Filing"],
      "created_at": "2025-10-01T08:00:00+00:00"
    }
  ],
  "meta": {"current_page": 1, "last_page": 1, "per_page": 50, "total": 1}
}

GET/api/roles

Get all roles (unpaginated)

Retrieve every role, unpaginated and ordered by name — used to populate role picker dropdowns.

Request

GET

/api/roles

curl https://your-domain.com/api/roles \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {token}" \
  --cookie "cms_admin_session={session}"

Response

{
  "data": [
    {"id": "...", "name": "BCC Evidence"},
    {"id": "...", "name": "BCC Staff"},
    {"id": "...", "name": "Branch of the Court Clerk"},
    {"id": "...", "name": "Counsel"},
    {"id": "...", "name": "Dashboard User"},
    {"id": "...", "name": "Office of the Court Clerk"},
    {"id": "...", "name": "Sheriff"},
    {"id": "...", "name": "Stenographer"},
    {"id": "...", "name": "Super Admin"},
    {"id": "...", "name": "User"}
  ]
}

POST/api/roles-list

Create a role

Create a new custom role with the specified permissions.

Required attributes

Name
name
Type
string
Description
The role name. Must be unique.
Name
permissions
Type
array
Description
Array of { "name": "..." } objects — see Permissions for valid permission names.

Request

POST

/api/roles-list

curl -X POST https://your-domain.com/api/roles-list \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {token}" \
  --cookie "cms_admin_session={session}" \
  -d '{
    "name": "Records Officer",
    "permissions": [{"name": "View Case Details"}, {"name": "View Case History"}]
  }'

Response

{
  "data": {
    "id": "3c2b1a09-8f7e-6d5c-3c2b-1a098f7e6d5c",
    "name": "Records Officer",
    "permissions": ["View Case Details", "View Case History"],
    "created_at": "2026-02-20T10:30:00+00:00"
  }
}

PUT/api/roles-list/{role}

Update a role

Sync a role's permission set. Does not currently rename the role even if a different name is submitted.

Path parameters

Name
role
Type
string
Description
The ID of the role to update.

Required attributes

Name
name
Type
string
Description
The role name (validated, but not applied as a rename).
Name
permissions
Type
array
Description
Array of { "name": "..." } objects. Replaces all existing permissions.

Request

PUT

/api/roles-list/{role}

curl -X PUT https://your-domain.com/api/roles-list/3c2b1a09-8f7e-6d5c-3c2b-1a098f7e6d5c \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {token}" \
  --cookie "cms_admin_session={session}" \
  -d '{
    "name": "Records Officer",
    "permissions": [{"name": "View Case Details"}, {"name": "View Case History"}, {"name": "Reports"}]
  }'

Response

{
  "data": {
    "id": "3c2b1a09-8f7e-6d5c-3c2b-1a098f7e6d5c",
    "name": "Records Officer",
    "permissions": ["View Case Details", "View Case History", "Reports"],
    "updated_at": "2026-02-20T11:00:00+00:00"
  }
}

DELETE/api/roles-list/{role}

Delete a role

Delete a custom role.

Path parameters

Name
role
Type
string
Description
The ID of the role to delete.

Request

DELETE

/api/roles-list/{role}

curl -X DELETE https://your-domain.com/api/roles-list/3c2b1a09-8f7e-6d5c-3c2b-1a098f7e6d5c \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {token}" \
  --cookie "cms_admin_session={session}"

Response

{
  "message": "Role deleted successfully."
}