GET	/api/roles/catalog
GET	/api/roles
GET	/api/roles/:id
POST	/api/roles
PUT	/api/roles/:id
POST	/api/roles/:id/reset
DELETE	/api/roles/:id

Catalog

GET/api/roles/catalog

Permission catalogue for the role editor.

Authentication: bearer token.
Permission: roles.view or users.assign_role.

curl -X GET "https://shellius.example.com/api/roles/catalog" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

List roles

GET/api/roles

Authentication: bearer token.
Permission: roles.view or users.assign_role.

curl -X GET "https://shellius.example.com/api/roles" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Retrieve role

GET/api/roles/:id

Authentication: bearer token.
Permission: roles.view.

Path parameters

Name	Type	Notes
id	string

curl -X GET "https://shellius.example.com/api/roles/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Create role

POST/api/roles

Authentication: bearer token.
Permission: roles.manage.

Request body

Name	Type	Required	Notes
name	string	Yes	1–60 characters.
description	string	No	At most 300 characters. May be null.
baseRole	string	No
permissions	object	No
copyFromRoleId	string	No	At most 100 characters.

curl -X POST "https://shellius.example.com/api/roles" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…"
  }'

201 Created

{ "success": true, "data": { … } }

Update role

PUT/api/roles/:id

Authentication: bearer token.
Permission: roles.manage.

Path parameters

Name	Type	Notes
id	string

Request body

Name	Type	Required	Notes
name	string	No	1–60 characters.
description	string	No	At most 300 characters. May be null.
baseRole	string	No
permissions	object	No

curl -X PUT "https://shellius.example.com/api/roles/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…",
    "description": "…",
    "baseRole": "…"
  }'

200 OK

{ "success": true, "data": { … } }

Reset

POST/api/roles/:id/reset

Authentication: bearer token.
Permission: roles.manage.

Path parameters

Name	Type	Notes
id	string

curl -X POST "https://shellius.example.com/api/roles/{id}/reset" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Delete role

DELETE/api/roles/:id

Authentication: bearer token.
Permission: roles.manage.

Path parameters

Name	Type	Notes
id	string

curl -X DELETE "https://shellius.example.com/api/roles/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }