Skip to Content
API ReferenceRoles API

Roles API

Endpoints for managing roles in the system.

Get Roles List

Get the complete list of roles.

Request

GET /api/roles

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "roles": [ { "id": 1, "name": "admin", "description": "Administrator" }, { "id": 2, "name": "moderator", "description": "Moderator" }, { "id": 3, "name": "user", "description": "User" } ] }

Response Fields

FieldTypeDescription
rolesarrayArray of roles
idintegerRole ID
namestringRole name
descriptionstringRole description

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request

Get Role Data

Get detailed information about a specific role.

Request

GET /api/roles/{id}

Path Parameters

NameTypeDescription
idintegerRole ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "role": { "id": 1, "name": "admin", "description": "Administrator", "permissions": [ { "id": 1, "name": "admin.users", "description": "User management" }, { "id": 2, "name": "admin.roles", "description": "Role management" } ] } }

Response Fields

FieldTypeDescription
roleobjectRole object
idintegerRole ID
namestringRole name
descriptionstringRole description
permissionsarrayArray of role permissions

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request
404Role not found

Create Role

Create a new role in the system.

Request

POST /api/roles

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "name": "editor", "description": "Content editor" }

Request Body Parameters

NameTypeDescription
namestringRequired. Role name
descriptionstringOptional. Role description

Response

{ "message": "Role created successfully", "role": { "id": 4, "name": "editor", "description": "Content editor" } }

Response Codes

CodeDescription
201Role successfully created
401Invalid or missing API key
403Insufficient permissions to perform request
422Invalid request parameters

Update Role

Update data of an existing role.

Request

PUT /api/roles/{id}

Path Parameters

NameTypeDescription
idintegerRole ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "name": "content-editor", "description": "Editor of all content types" }

Request Body Parameters

NameTypeDescription
namestringOptional. Role name
descriptionstringOptional. Role description

Response

{ "message": "Role updated successfully", "role": { "id": 4, "name": "content-editor", "description": "Editor of all content types" } }

Response Codes

CodeDescription
200Role successfully updated
401Invalid or missing API key
403Insufficient permissions to perform request
404Role not found
422Invalid request parameters

Delete Role

Delete a role from the system.

Request

DELETE /api/roles/{id}

Path Parameters

NameTypeDescription
idintegerRole ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "message": "Role deleted successfully" }

Response Codes

CodeDescription
200Role successfully deleted
401Invalid or missing API key
403Insufficient permissions to perform request
404Role not found

Manage Role Permissions

Change the permissions list for a role.

Request

PUT /api/roles/{id}/permissions

Path Parameters

NameTypeDescription
idintegerRole ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "permission_ids": [1, 2, 3] }

Request Body Parameters

NameTypeDescription
permission_idsarrayRequired. Array of permission IDs

Response

{ "message": "Role permissions updated successfully", "role": { "id": 4, "name": "content-editor", "description": "Editor of all content types", "permissions": [ { "id": 1, "name": "admin.users", "description": "User management" }, { "id": 2, "name": "admin.roles", "description": "Role management" }, { "id": 3, "name": "admin.pages", "description": "Page management" } ] } }

Response Codes

CodeDescription
200Role permissions successfully updated
401Invalid or missing API key
403Insufficient permissions to perform request
404Role not found
422Invalid request parameters