Retrieving permissions

The first step in working with permissions may simply be retrieving permissions. An administrator may want to retrieve a list of all supported permissions, or retrieve the permissions for a role, user, or data source.

Note: Administrators can also retrieve permissions on data sources that are shared with users and tenants. See Data Sources API and Sharing data sources for details.

Retrieve supported permissions

An administrator can retrieve information on all supported permissions using the Administrator Permissions API. A user must have either the Administrator (12) or MgmtAPI (11) to use this API.

GET https://MyServer:8443/api/admin/permissions

{
"permissions": [
{
"id": 1,
"name": "CreateDataSource",
"description": "May create new data sources."
},
{
"id": 2,
"name": "ViewDataSource",
"description": "May view any data source they own (when given to a role
or user) or view an individual data source they own (when given to a data source)."
},
{
"id": 3,
"name": "ModifyDataSource",
"description": "May modify/update any data source they own (when given
to a role or user) or modify/update an individual data source they own (when given
to a data source)."
},
...
]
}

Retrieve roles and permissions on a role

A role ID is required to retrieve permissions on a role. Therefore, an administrator may need to retrieve roles before requesting permissions on a role. The Roles API can be used to retrieve roles and then permissions associated with a specific role.

The following request retrieves the roles for a Hybrid Data Pipeline service. The user must have the Administrator (12) permission, or the ViewRole (18) permission and administrative access on the tenant.

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

{
"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."
}
]
}

With the role ID, an administrator can retrieve the permissions associated with a role. This request also returns the users that have been assigned the role. The user must have the Administrator (12) permission, or the ViewRole (18) permission and administrative access on the tenant.

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

{
"name": "User",
"tenantId": 1,
"description": "This role has the default permissions that a normal user will
be expected to have.",
"permissions": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11
],
"users": [
2,
9,
46
]
}

Retrieve effective permissions on a user

An administrator can retrieve permissions on a user with either the Management Permissions API or the Users API. The permissions for a user are the sum of the permissions granted to the user's role(s) and permissions granted explicitly to the user.

The following Management Permissions API request returns the list of effective permissions for the user by specifying the user's name with the user query parameter (?user). The administrator must have the Administrator (12) permission; or the administrator must have the MgmtAPI (11) permission, the OnBehalfOf (21) permission, and administrative access on the tenant to which the user belongs.

GET https://MyServer:8443/api/mgmt/permissions?user=d2cuser

{
"userId": 2,
"permissions": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11
]
}

The following Users API request returns a roles object that shows the roles assigned to the user, and a permissions object that shows the permissions that have been explicitly set on the user. The {id} is the auto-generated user ID. The administrator must have the Administrator (12) permission, or the ViewUsers (14) permission and administrative access on the tenant to which the user belongs.

GET https://MyServer:8443/api/admin/users/{id}/permissions

{
"roles": [
5
],
"permissions": [
8,
9,
10
]
}

Retrieve permissions on a data source

The following Data Sources API request retrieves permissions on a specific data source on behalf of the data source owner. The {datasourceId} is the auto-generated data source ID, and the user query parameter (?user) is used to specify the owner of the data source. The administrator must have the Administrator (12) permission; or the administrator must have the MgmtAPI (11) permission, the OnBehalfOf (21) permission, administrative access on the tenant to which the user belongs, and the ViewDataSource (2) permission.

Note: When no permissions have been set on a data source, then the permissions of the user are returned. When permissions have been set on a data source, they will be returned instead of the user's permissions. The permissions on a data source override the user's permissions.