Roles API in Wasabi AiR

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

Listing Roles

GET /api/data/roles

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.

Retrieving a Role

GET /api/data/roles/{id}

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

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.

Response

The response is 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.

Viewing Users Assigned to a Role

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

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

Response

The response is 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"
    }
]

Refer to the Users and Groups API for a detailed description of each field on the User objects.

Listing Available Scopes

GET /api/data/roles/scopes

Response

The response is 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 which to add the scopes.

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

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

Response

The response is 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 from which to remove the scopes.
• {scopes} - (string) A comma-delimited list of scopes to remove from the scope.

For example: DELETE /roles/5b108fd38dc67a7042c93cb073333207/scopeB,scopeC

Response

The response is 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"
    ]
}