Roles

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.

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.

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)

Last updated