The following operations show how the Roles API can be used to retrieve roles, create roles, retrieve details on a role, and update the permissions on a role.

Note: Hybrid Data Pipeline provides three default roles in the system tenant: System Administrator, Tenant Administrator, and User. The System Administrator role has all permissions, the Tenant Administrator role has tenant and user permissions, and the User role has only user permissions. These roles cannot be deleted, and only the users associated with them can be modified. (See also Permissions and default roles.)

Retrieve current roles

The following request will retrieve current roles in the Hybrid Data Pipeline service. The administrator must have the Administrator (12) permission, or the ViewRole (18) permission and administrative access on the tenant.

Request

GET https://MyServer:8443/api/admin/roles
Note: The ?tenantID=<tenant_id> and ?tenantName=<tenant_name> query parameters can be appended to the URL to limit the roles returned to a specific tenant.

Response Payload

{
    "roles": [
        {
            "id": 1,
            "name": "Administrator",
            "tenantId": 1,
            "description": "This role has all permissions. This role cannot be
modified or deleted."
        },
        {
            "id": 2,
            "name": "User",
            "tenantId": 1,
            "description": "This role has the default permissions that a normal
user will be expected to have."
        },
        {
            "id": 3,
            "name": "Tenant Administrator",
            "tenantId": 1,
            "description": "This role has all the tenant administrator permissions."
        }
    ]
}

Create a new role

With the following POST request, a new role is created which allows OData-only access to three users as specified with the "users" property. The administrator must have the Administrator (12) permission, or the CreateRole (17) permission and administrative access on the tenant.

Request

POST https://MyServer:8443/api/admin/roles

Request Payload

{
   "name": "ODataOnly",
   "tenantId": 1,
   "description": "This role allows only OData access.",
   "permissions": [7],
   "users": [209,304,408]
}

Response Payload

{
   "id": 37
   "name": "ODataOnly",
   "tenantId": 1,
   "description": "This role allows only OData access.",
   "permissions": [
        7
   ],
   "users": [
        209,
        304,
        408
   ]
}

Retrieve details on new role

An administrator can then retrieve details on the new role, including permissions and users, with the following GET request. The role ID 37 is passed in the request URL. The administrator must have the Administrator (12) permission, or the ViewRole (18) permission and administrative access on the tenant.

Request

GET https://MyServer:8443/api/admin/roles/37

Response Payload

{
   "id": 37,
   "name": "ODataOnly",
   "tenantId": 1,
   "description": "This role allows only OData access.",
   "permissions": [
        7
   ],
   "users": [
        209,
        304,
        408
   ]
}

Update permissions on new role

An administrator can also use a PUT request to update permissions and users associated with the new role. The following request adds the WebUI, ChangePassword, MgmtAPI, and SQL editor permissions (all required to use the SQL editor). It also assigns the role to an additional user. The administrator must have the Administrator (12) permission, or the ModifyRole (19) permission and administrative access on the tenant.

Request

PUT https://MyServer:8443/api/admin/roles/37

Request Payload

{
   "id": 37,
   "name": "ODataOnly",
   "tenantId": 1,
   "description": "This role allows OData access and access to the Web UI SQL
editor. It includes the UseDataSourceWithOData, WebUI, ChangePassword, MgmtAPI,
and SQL editor permissions.",
   "permissions": [
        7,
        8,
        9,
        10,
        11	
   ],
   "users": [
        209,
        304,
        408,
        503
   ]
}

Response Payload

{
   "id": 37,
   "name": "ODataOnly",
   "tenantId": 1,
   "description": "This role allows OData access and access to the Web UI SQL
editor. It includes the UseDataSourceWithOData, WebUI, ChangePassword, MgmtAPI,
and SQL editor permissions.",
   "permissions": [
        7,
        8,
        9,
        10,
        11
   ],
   "users": [
        209,
        304,
        408,
        503
   ]
}