Get permissions
GET/permissions
Base URL: https://api.tinkermode.com
Get a list of permissions of a resource (by using the resourceId parameter), permissions of a user (by using the userId parameter),
permissions of a service account (by using the serviceAccountId parameter),
or permissions of an access control group (by using the accessControlGroupId parameter)
Either the resourceId, userId, serviceAccountId, or accessControlGroupId must be specified.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a user, service account, or project API key with "Admin" privileges.
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
accessControlGroupId | integer | No | Return permissions of the access control group. | |
limit | integer | No | default: 25; min: 1; max: 100 | Maximum number of permissions to return. |
projectId | integer | Yes | Return permissions of the specified project. | |
resolveUserPermissions | boolean | No | This is only used with the userId parameter. If true, the result includes not only the user's permissions but also the permissions of the access control groups that the user belongs to. Also, when the resourceType and resourceId parameters are also specified, the result includes relevant permissions to be applied to the resource access. For example, when the user has permission on all "" home resources and makes a request to get permissions with resourceType=home&resourceId=123, the "" permission will be returned because it is the permission to be applied for the resource access. Similarly, an entity can inherit permissions from ancestors. This returns ancestors' permissions in addition to direct permissions on the entity if the resourceType is "entity" and resourceID is specified. | |
resourceId | string | No | Return permissions of the resource. The resourceType must be also specified. | |
resourceType | string | No | Return permissions of the resource. The resourceId must be also specified. | |
serviceAccountId | integer | No | Return permissions of the service account. The caller must be a project API key with "Admin" privileges or a super admin user in a project with permission based access control enabled. | |
skip | integer | No | default: 0; min: 0 | Number of permissions to skip over. |
sortBy | string | No | The sort order of the permissions in the format field:order (e.g. resourceType:desc). Currently, only the resourceType field is supported. The default order is ascending. | |
userId | integer | No | Return permissions of the user. |
Responses
200 Successful retrieval of list of permissions.
Content type: application/json
Represents a permission statement that defines resource access policy.
An array of objects with the following shape:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
actions | array<string> | Yes | Allowed/denied actions | |
effect | string | Yes | one of: allow, deny | Access policy |
id | integer | Yes | read-only (server-generated) | Unique ID assigned at time of creation. |
principalId | integer | Yes | read-only (server-generated) | Principal ID such as a user ID or service account ID |
principalType | string | Yes | read-only (server-generated); one of: user, accessControlGroup, serviceAccount | Principal type |
projectId | integer | Yes | read-only (server-generated) | Project that this permission belongs to. |
resourceIdentifier | string | Yes | Resource ID (e.g., user ID, entity ID). * represents all for supported resource types; for entity, use root instead of *. | |
resourceScope | string | No | one of: self, selfWithDescendants | Resource scope. Only Entity supports resource scope. |
resourceType | string | Yes | read-only (server-generated); one of: all, accessControlGroup, user, home, entity, entityClass, device, alertRule, alertSchedule, projectLog, projectAlert, projectFile, dataFilter, assistant, projectBizstackApp | Resource type |
statementType | string | Yes | read-only (server-generated); one of: principalBased | Statement type |
subResources | array<object> | No | Array of sub-resource permissions |
Response example
[
{
"id": 12,
"projectId": 2,
"statementType": "principalBased",
"principalType": "user",
"principalId": 2,
"resourceType": "entity",
"resourceIdentifier": "room_123",
"resourceScope": "self",
"actions": [
"read",
"create",
"update",
"delete",
"managePermissions"
],
"effect": "allow",
"subResources": [
{
"resourceType": "entityMetrics",
"actions": [
"read",
"delete"
],
"effect": "allow"
}
]
},
{
"id": 13,
"projectId": 2,
"statementType": "principalBased",
"principalType": "user",
"principalId": 2,
"resourceType": "homes",
"resourceIdentifier": "2",
"actions": [
"read",
"create",
"update",
"delete",
"managePermissions"
],
"effect": "allow"
}
]
401 Authorization is required to access this resource.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
403 Request failed because of denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
429 Request failed because of rate limit.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |