Roles API
Endpoints for managing roles in the system.
Get Roles List
Get the complete list of roles.
Request
GET /api/rolesHeaders
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. API key |
Response
{
"roles": [
{
"id": 1,
"name": "admin",
"description": "Administrator"
},
{
"id": 2,
"name": "moderator",
"description": "Moderator"
},
{
"id": 3,
"name": "user",
"description": "User"
}
]
}Response Fields
| Field | Type | Description |
|---|---|---|
| roles | array | Array of roles |
| id | integer | Role ID |
| name | string | Role name |
| description | string | Role description |
Response Codes
| Code | Description |
|---|---|
| 200 | Successful request |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
Get Role Data
Get detailed information about a specific role.
Request
GET /api/roles/{id}Path Parameters
| Name | Type | Description |
|---|---|---|
| id | integer | Role ID |
Headers
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. 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
| Field | Type | Description |
|---|---|---|
| role | object | Role object |
| id | integer | Role ID |
| name | string | Role name |
| description | string | Role description |
| permissions | array | Array of role permissions |
Response Codes
| Code | Description |
|---|---|
| 200 | Successful request |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
| 404 | Role not found |
Create Role
Create a new role in the system.
Request
POST /api/rolesHeaders
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. API key |
| Content-Type | string | Required. application/json |
Request Body
{
"name": "editor",
"description": "Content editor"
}Request Body Parameters
| Name | Type | Description |
|---|---|---|
| name | string | Required. Role name |
| description | string | Optional. Role description |
Response
{
"message": "Role created successfully",
"role": {
"id": 4,
"name": "editor",
"description": "Content editor"
}
}Response Codes
| Code | Description |
|---|---|
| 201 | Role successfully created |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
| 422 | Invalid request parameters |
Update Role
Update data of an existing role.
Request
PUT /api/roles/{id}Path Parameters
| Name | Type | Description |
|---|---|---|
| id | integer | Role ID |
Headers
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. API key |
| Content-Type | string | Required. application/json |
Request Body
{
"name": "content-editor",
"description": "Editor of all content types"
}Request Body Parameters
| Name | Type | Description |
|---|---|---|
| name | string | Optional. Role name |
| description | string | Optional. Role description |
Response
{
"message": "Role updated successfully",
"role": {
"id": 4,
"name": "content-editor",
"description": "Editor of all content types"
}
}Response Codes
| Code | Description |
|---|---|
| 200 | Role successfully updated |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
| 404 | Role not found |
| 422 | Invalid request parameters |
Delete Role
Delete a role from the system.
Request
DELETE /api/roles/{id}Path Parameters
| Name | Type | Description |
|---|---|---|
| id | integer | Role ID |
Headers
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. API key |
Response
{
"message": "Role deleted successfully"
}Response Codes
| Code | Description |
|---|---|
| 200 | Role successfully deleted |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
| 404 | Role not found |
Manage Role Permissions
Change the permissions list for a role.
Request
PUT /api/roles/{id}/permissionsPath Parameters
| Name | Type | Description |
|---|---|---|
| id | integer | Role ID |
Headers
| Name | Type | Description |
|---|---|---|
| X-API-Key | string | Required. API key |
| Content-Type | string | Required. application/json |
Request Body
{
"permission_ids": [1, 2, 3]
}Request Body Parameters
| Name | Type | Description |
|---|---|---|
| permission_ids | array | Required. 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
| Code | Description |
|---|---|
| 200 | Role permissions successfully updated |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions to perform request |
| 404 | Role not found |
| 422 | Invalid request parameters |