Roles API

The Roles API allows you to control role based access control (RBAC).

List Roles

GET /api/data/roles

You will receive the following response:

{
    "roles": [
        {
            "description": "Users in this role only have access to view metadata in the platform",
            "id": "67779468b22af637e2dd6a26abcd1234",
            "name": "Read Only"
        },
        {
            "description": "Super Administrator Role",
            "id": "67779468b22af637e2dd6a2616264b6c",
            "name": "Super Admin"
        }
    ]
}

roles[].description - (string) A human-readable description of the role
roles[].id - (string) The ID of the role
roles[].name - (string) A human-readable display name of the role

Retrieve a Role

GET /api/data/roles/{id}

{id} - (string) The ID of the role to get

You will receive the following response:

{
    "description": "Users in this role only have access to view metadata in the platform",
    "id": "67779468b22af637e2dd6a26abcd1234",
    "name": "Read Only",
    "scopes": [
        "scopeA",
        "scopeB"
    ]
}

description - (string) A human-readable description of the role
id - (string) The ID of the role
name - (string) A human-readable display name of the role
scopes[] - (string) A list of scopes that belong to this role.

Creating a Role

POST /api/data/roles

{
    "description": "Users in this role only have access to view metadata in the platform",
    "name": "Read Only",
    "scopes": [
        "scopeA",
        "scopeB"
    ]
}

description - (string) A human-readable description of the role
id - (string) The ID of the role
name - (string) A human-readable display name of the role
scopes[] - (string) Optional. A list of scopes that belong to this role.

The response will be 201, with the Role object:

{
    "description": "Users in this role only have access to view metadata in the platform",
    "id": "5b108fd38dc67a7042c93cb073333207",
    "name": "Read Only",
    "scopes": [
        "scopeA",
        "scopeB"
    ]
}

Deleting a Role

DELETE /api/data/roles/{id}

{id} - (string) The ID of the role to delete

Note: The role must not be assigned to any users in order for it to be deleted

Viewing Users Assigned To a Role

GET /api/data/roles/{id}/users

{id} - (string) The ID of the role to get users from

The response will be 200, with an array of Users objects:

[
    {
        "admin": false,
        "avatar": "",
        "company_uid": "",
        "created_at": "2018-06-01T00:00:00Z",
        "email": "a@example.com",
        "enabled": true,
        "first_name": "User",
        "groups": {
            "count": 0,
            "shortlist": null
        },
        "id": "5b116ed9a5c3f50e3c2d87cf70f5df3d",
        "last_name": "A",
        "role_id": "5b108fd38dc67a7042c93cb073333207",
        "updated_at": "2018-06-01T16:05:45.254213Z"
    },
    {
        "admin": false,
        "avatar": "",
        "company_uid": "",
        "created_at": "2018-06-01T00:00:00Z",
        "email": "b@example.com",
        "enabled": true,
        "first_name": "User",
        "groups": {
            "count": 0,
            "shortlist": null
        },
        "id": "5b116ee42da0fef4ff08f719fe0a4a34",
        "last_name": "B",
        "role_id": "5b108fd38dc67a7042c93cb073333207",
        "updated_at": "2018-06-01T16:05:56.882066Z"
    }
]

Please see the Users Documentation for a detailed description of each of the fields on the user objects.

Listing Available Scopes

GET /api/data/roles/scopes

The response will be 200, with an array of ScopeGroup objects:

[
    {
        "name": "Comments",
        "scopes": [
            {
                "display_name": "Create Comments",
                "name": "comment:create"
            },
            {
                "display_name": "Read Comments",
                "name": "comment:get"
            }
        ],
        "sort_order": 0
    },
    {
        "name": "Items",
        "scopes": [
            {
                "display_name": "Delete Items",
                "name": "item:delete"
            },
            {
                "display_name": "Download Items",
                "name": "item:download"
            }
        ],
        "sort_order": 0
    },
    ...
]

[].name - (string) A human readable name of the scope group
[].sort_order - (integer) A value indicating the sort order of the scope group
[].scopes[].display_name - (string) A human readable name/description of the scope
[].scopes[].name - (string) The name of the scope. This is the string to use when adding/removing scopes to/from roles

Adding One or More Scopes to an Existing Role

POST /roles/{id}

{id} - (string) The ID of the role to add the scopes to

{
    "scopes": [
        "scopeA",
        "scopeB"
    ]
}

scopes[] - (string) A list of scopes to add to this role.

The response will be 200, with the Role object:

{
    "description": "Users in this role only have access to view metadata in the platform",
    "id": "5b108fd38dc67a7042c93cb073333207",
    "name": "Read Only",
    "scopes": [
        "scopeA",
        "scopeB",
        "scopeC"
    ]
}

Removing One or More Scopes from a Role

DELETE /roles/{id}/{scopes}

{id} - (string) The ID of the role to remove the scopes from
{scopes} - (string) A comma delimited list of scopes to remove from the scope

Example: DELETE /roles/5b108fd38dc67a7042c93cb073333207/scopeB,scopeC.