Roles

The roles namespace provides API methods to retrieve all or specific user roles. This page covers the following API methods:

• GET /roles

• GET /roles/{role_id}

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

Parameters

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.

Schema

"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

Parameters

expands string Comma-separated list of expands to return.

Schema

"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)