The roles namespace provides API methods to retrieve all or specific user roles. This page covers the following API methods:
GET /roles
Returns all roles. Requires site admin access.
This method uses pagination so you might need to request additional pages to retrieve all roles.
Request
page integer
Number of page to return (default: first page)
per_page integer
Maximum number of roles to return (supported: 15, 25, 50, 100; default: 100)
expands string
Comma-separated list of expands to return.
"page": {
"type": "integer",
"format": "int64",
"description": "Number of page (default: first page)."
},
"per_page": {
"type": "integer",
"format": "int64",
"enum": [
15,
25,
50,
100
],
"description": "Maximum number of items to return per page (default: 100)."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}This method supports the following expands so you can automatically include additional information for referenced objects:
users
Response
GET /api/v1/roles
200 OK
{
"page": 1,
"prev_page": null,
"next_page": null,
"last_page": 1,
"per_page": 100,
"total": 4,
"result": [
{
"id": 1,
"name": "Read-only",
"permissions": 0,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
{
"id": 2,
"name": "Tester",
"permissions": ..,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
..
],
"expands": {
..
}
}
Examples
// Get first 100 roles
GET /api/v1/roles
// Get second result page (pagination)
GET /api/v1/roles?page=2
// Get roles and include user details
GET /api/v1/roles?expands=users
Status codes
200 400 401 403 422 (details)
GET /roles/{role_id}
Returns a single role. Requires site admin access.
role_id id required
ID of the role to return.
Request
expands string Comma-separated list of expands to return.
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}This method supports the following expands so you can automatically include additional information for referenced objects:
users
Response
GET /api/v1/roles/1
200 OK
{
"result": {
"id": 1,
"name": "Read-only",
"permissions": 0,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
"expands": {
..
}
}
Examples
// Get the role with ID 5
GET /api/v1/roles/5
// Get a role and include user details
GET /api/v1/roles/1?expands=users
Status codes
200 400 401 403 404 422 (details)