Roles

Roles API

The Roles API provides endpoints to manage user roles and permissions in your PoloCloud instance.

Manage user roles, permissions, and access control via REST API

Create Role

Create a new role with specified permissions and styling.

Endpoint: POST /polocloud/api/v3/role/

Request Body:

{
  "label": "Moderator",
  "hexColor": "#00FF00",
  "permissions": [
    "polocloud.player.get",
    "polocloud.players.list",
    "polocloud.group.get"
  ]
}

Response:

{
  "status": 201,
  "data": {
    "id": 2,
    "label": "Moderator",
    "hexColor": "#00FF00",
    "default": false,
    "permissions": [
      "polocloud.player.get",
      "polocloud.players.list",
      "polocloud.group.get"
    ]
  }
}

Error Responses:

400 - Role label is required / Role hexColor is required / Role already exists
403 - You cannot assign * permission

List Roles

Retrieve all available roles with user counts.

Endpoint: GET /polocloud/api/v3/roles/

Response:

{
  "status": 200,
  "data": [
    {
      "id": -1,
      "label": "Admin",
      "hexColor": "#FF0000",
      "default": true,
      "permissions": ["*"],
      "userCount": 1
    },
    {
      "id": 2,
      "label": "Moderator",
      "hexColor": "#00FF00",
      "default": false,
      "permissions": [
        "polocloud.player.get",
        "polocloud.players.list"
      ],
      "userCount": 3
    }
  ]
}

Get Role

Retrieve detailed information about a specific role by ID.

Endpoint: GET /polocloud/api/v3/role/{id}

Parameters:

id (path) - The ID of the role to retrieve

Response:

{
  "status": 200,
  "data": {
    "id": 2,
    "label": "Moderator",
    "hexColor": "#00FF00",
    "default": false,
    "permissions": [
      "polocloud.player.get",
      "polocloud.players.list"
    ]
  }
}

Error Responses:

400 - Invalid role ID
404 - Role not found

Edit Role

Update an existing role's properties and permissions.

Endpoint: PATCH /polocloud/api/v3/role/{id}

Parameters:

id (path) - The ID of the role to update

Request Body:

{
  "label": "Senior Moderator",
  "hexColor": "#0080FF",
  "permissions": [
    "polocloud.player.get",
    "polocloud.players.list",
    "polocloud.group.get",
    "polocloud.group.create"
  ]
}

Response:

{
  "status": 200,
  "data": {
    "id": 2,
    "label": "Senior Moderator",
    "hexColor": "#0080FF",
    "default": false,
    "permissions": [
      "polocloud.player.get",
      "polocloud.players.list",
      "polocloud.group.get",
      "polocloud.group.create"
    ]
  }
}

Error Responses:

400 - Invalid role ID / Role label is required / Role hexColor is required
403 - You cannot assign * permission
404 - Role not found

Delete Role

Delete a role (cannot delete default roles).

Endpoint: DELETE /polocloud/api/v3/role/{id}

Parameters:

id (path) - The ID of the role to delete

Response:

{
  "status": 204
}

Error Responses:

400 - Invalid role ID
404 - Role not found or cannot be deleted
500 - Failed to delete role

Role Model

Field	Type	Description
`id`	number	Unique role identifier
`label`	string	Display name of the role
`hexColor`	string	Color code for the role (e.g., "#FF0000")
`default`	boolean	Whether this is a default system role
`permissions`	array	List of permission strings
`userCount`	number	Number of users with this role (list only)

Usage Examples

Create a New Role

curl -X POST "http://localhost:8080/polocloud/api/v3/role/" \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
    "label": "Moderator",
    "hexColor": "#00FF00",
    "permissions": ["polocloud.player.get", "polocloud.players.list"]
  }'

List All Roles

curl -X GET "http://localhost:8080/polocloud/api/v3/roles/" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Get Specific Role

curl -X GET "http://localhost:8080/polocloud/api/v3/role/2" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Update Role

curl -X PATCH "http://localhost:8080/polocloud/api/v3/role/2" \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
    "label": "Senior Moderator",
    "hexColor": "#0080FF",
    "permissions": ["polocloud.player.get", "polocloud.players.list", "polocloud.group.get"]
  }'

Delete Role

curl -X DELETE "http://localhost:8080/polocloud/api/v3/role/2" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Roles

On this page