Roles API
Endpoints for managing roles in the system.
Get Roles List
Get the complete list of roles.
Request
GET /api/roles
Headers
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/roles
Headers
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}/permissions
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
{
"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 |