Permissions API

For more information about Permissions, read the feature guide.

CREATE_PRIVILEGE

Required role: ReadWrite
Required privilege: Permissions.UPDATE on the domainId of the role
Required privilege: Permissions.CREATE on the domainId of the privilege

Creates a privilege for a role.

API Endpoint: [POST]: /permissions/privileges

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Body

roleId: Id of an already existing role that the privilege should be added to. required
objectName: The privilege object that the privilege applies to. required
domainId: The domain where the privilege applies. required if type is regular, forbidden otherwise.
name: A name for the privilege. Max length 128 characters.
create: Whether the privilege gives create privilege or not. Default is 0. ( 0 | 1)
read: Whether the privilege gives read privilege or not. Default is 0. ( 0 | 1)
update: Whether the privilege gives update privilege or not. Default is 0. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. Default is 0. ( 0 | 1)

At least one of create, read, update, delete is required.

Example payloads

# Allow getting and finding things in Thing Management API and add/remove things from groups in Thing Group API
{
  "roleId": "e4d3c4a2424bb721",
  "objectName": "Things",
  "domainId": "domain1",
  "name": "Read and Update Things in domain1",
  "read": 1,
  "update": 1
}

# Allow subscribing to topics of Things in domain1
{
  "roleId": "e4d3c4a2424bb721",
  "objectName": "ThingPubSub",
  "domainId": "domain1",
  "name": "Subscribe to topics in domain1",
  "read": 1
}

# Deny access to App Board
{
  "roleId": "e4d3c4a2424bb721",
  "objectName": "AppBoard",
  "name": "Deny access to App Board"
}

Response

id: The generated ID of the privilege.
roleId: The ID of the role that the privilege belongs to.
objectName: The privilege object that the privilege applies to.
domainId: The domain where the privilege applies. Included if type of the privilege is regular.
type: The type of the privilege. ( regular | settings)
name: The name of the privilege.
create: Whether the privilege gives create privilege or not. ( 0 | 1)
read: Whether the privilege gives read privilege or not. ( 0 | 1)
update: Whether the privilege gives update privilege or not. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. ( 0 | 1)

Errors

Key	Property	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`ROLE_NOT_FOUND`	`roleId`	Returned if the specified role could not be found or is inaccessible.
`DOMAIN_NOT_FOUND`	`domainId`	Returned if the specified domain could not be found or is inaccessible.
`PRIVILEGE_ALREADY_EXISTS`	`roleId`, `objectName`	Returned if the role already has a privilege for the specified object.
`POLICY_DOCUMENT_LIMIT_EXCEEDED`		Returned if the policy document is longer than 2048 characters

GET_PRIVILEGE

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role
Required privilege: Permissions.READ on the domainId of the privilege

Gets information about a privilege.

API Endpoint: [GET]: /permissions/privileges/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the privilege to get required

Response

id: The ID of the privilege.
roleId: The ID of the role that the privilege belongs to.
objectName: The privilege object that the privilege applies to.
domainId: The domain where the privilege applies. Included if type of the privilege is regular.
type: The type of the privilege. ( regular | settings)
name: The name of the privilege.
create: Whether the privilege gives create privilege or not. ( 0 | 1)
read: Whether the privilege gives read privilege or not. ( 0 | 1)
update: Whether the privilege gives update privilege or not. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. ( 0 | 1)

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`PRIVILEGE_DOES_NOT_EXIST`	`id`	Returned if the privilege does not exist or the role of the privilege is inaccessible.

UPDATE_PRIVILEGE

Required role: ReadWrite
Required privilege: Permissions.UPDATE on the domainId of the role
Required privilege: Permissions.UPDATE on the domainId of the privilege

Updates a privilege. Any field specified will replace the old value of that field. Any field not specified will keep its old value.

API Endpoint: [PATCH]: /permissions/privileges/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the privilege to update required

Body

name: A name for the privilege. Max length 128 characters.
create: Whether the privilege gives create privilege or not. Default is 0. ( 0 | 1)
read: Whether the privilege gives read privilege or not. Default is 0. ( 0 | 1)
update: Whether the privilege gives update privilege or not. Default is 0. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. Default is 0. ( 0 | 1)

Example payload

{
  "create": 0,
  "read": 1
}

Response

id: The ID of the privilege
roleId: The ID of the role that the privilege belongs to.
objectName: The privilege object that the privilege applies to.
domainId: The domain where the privilege applies. Included if the type of the privilege is regular.
name: The name of the privilege.
type: The type of the privilege. ( regular | settings)
create: Whether the privilege gives create privilege or not. ( 0 | 1)
read: Whether the privilege gives read privilege or not. ( 0 | 1)
update: Whether the privilege gives update privilege or not. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. ( 0 | 1)

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`PRIVILEGE_DOES_NOT_EXIST`	`id`	Returned if the the privilege does not exist.
`POLICY_DOCUMENT_LIMIT_EXCEEDED`		Returned if the new policy document is longer than 2048 characters
`POLICY_NOT_ATTACHED`		Returned if new policy could not be attached to all users.

REMOVE_PRIVILEGE

Required role: ReadWrite
Required privilege: Permissions.UPDATE on the domainId of the role
Required privilege: Permissions.DELETE on the domainId of the privilege

Removes a privilege from a role.

API Endpoint: [DELETE]: /permissions/privileges/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the privilege to remove required

Response

Empty JSON object: {}

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`PRIVILEGE_DOES_NOT_EXIST`	`id`	Returned if the privilege does not exist or if the role of the privilege is inaccessible.

CREATE_ROLE

Required role: ReadWrite
Required privilege: Permissions.CREATE on the domainId of the role

Creates a new role.

API Endpoint: [POST]: /permissions/roles

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Body

name: The name of the role required
domainId: The domain which needs to be accessible in order to create, read, update, or delete the role required
description: An optional description
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )

Example payloads

{
  "name": "MyRole",
  "domainId": "root",
  "description": "a description",
}

{
  "name": "MyGenericRole",
  "domainId": "root",
  "description": "Role to be used everywhere",
  "visibleInSubdomains": true
}

Response

id: The ID of the role.
name: The name of the role.
domainId: The domain of the role.
description: A description of the role or null.
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )
createdAt: An epoch timestamp in milliseconds, when the role was created.
updatedAt: An epoch timestamp in milliseconds, when the role was updated or null.

Errors

Key	Property	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`DOMAIN_NOT_FOUND`	`domainId`	Returned if domainId is not found or is not accessible.

GET_ROLE

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role or on a subdomain if the role is visible in subdomains

Get a role by its ID.

API Endpoint: [GET]: /permissions/roles/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the role required

Response

id: The ID of the role.
name: The name of the role.
domainId: The domain of the role.
description: A description of the role, if it exists. Otherwise null.
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )
createdAt: An epoch timestamp in milliseconds, when the role was created.
updatedAt: An epoch timestamp in milliseconds when the role was updated, if it exists. Otherwise null.

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`	`id`	Returned if a parameter does not fulfil requirements.
`ROLE_NOT_FOUND`	`id`	Returned if the role does not exist or is inaccessible.

UPDATE_ROLE

Required role: ReadWrite
Required privilege: Permissions.UPDATE on the domainId of the role
Optional privilege: Permissions.CREATE on added domainId
Optional privilege: Permissions.DELETE on removed domainId

Updates a role.

API Endpoint: [PATCH]: /permissions/roles/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the role required

Body

name: The new name of the role.
domainId: The new domain which needs to be accessible in order to CRUD the role.
description: The new description.
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )

Example payloads

{
  "name": "NewNameOfMyRole",
  "description": "A new description of the role"
}

The following payload would require the optional privileges Permissions.DELETE on the existing domainId of the role and Permissions.CREATE on otherDomain (the domain specified in the request).

{
  "name": "NewNameOfMyRole",
  "domainId": "otherDomain"
}

Response

id: The ID of the role.
name: The name of the role.
domainId: The domain of the role.
description: A description of the role if it exists. Otherwise null.
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )
createdAt: An epoch timestamp in milliseconds, when the role was created.
updatedAt: An epoch timestamp in milliseconds, when the role was updated.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		`name`, `description`	Returned if a parameter does not fulfil requirements.
`DOMAIN_NOT_FOUND`		`domainId`	Returned if domainId is not found or is not accessible.
`ROLE_NOT_FOUND`	`id`		Returned if the role does not exist or is inaccessible.

REMOVE_ROLE

Required role: ReadWrite
Required privilege: Permissions.DELETE on the domainId of the role

Removes the role, all privileges of the role, and all users from that role.

API Endpoint: [DELETE]: /permissions/roles/{id}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the role to remove required

Response

Empty JSON object: {}

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`ROLE_NOT_FOUND`	`id`	Returned if the role could not be found or is inaccessible.

LIST_ROLES

Required role: Read
Required privilege: Permissions.READ on at least one domain

List all roles.

API Endpoint: [GET]: /permissions/roles

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Query Parameters

attributes: A comma-delimited string of attributes that should be included in the response. If empty or not set, all attributes will be returned.
domainId: The domain id for which the domain specific roles should be retrieved.

Response

id: The ID of the role.
name: The name of the role.
domainId: The domain of the role.
description: A description of the role if it exists. Otherwise null.
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )
createdAt: An epoch timestamp in milliseconds when the role was created.
updatedAt: An epoch timestamp in milliseconds when the role was updated, if it exists. Otherwise null.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`			Returned if a query parameter does not fulfil requirements.

GET_ROLES

Required role: Read
Required privilege: Permissions.READ on at least one domain

List roles supporting pagination and specifying response size

API Endpoint: [GET]: /permissions/roles/list

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Query Parameters

attributes: A comma-delimited string of attributes that should be included in the response. If empty or not set, all attributes will be returned.
domainId: The domain id for which the domain specific roles should be retrieved.
size: The desired page size. (max 100) optional
marker: The marker to get the next page. Received in previous response. optional

Example request

GET: /permissions/roles/list?size=10&marker=someMarker

Response

roles: The list of roles.
- id: The ID of the role.
- name: The name of the role.
- domainId: The domain of the role.
- description: A description of the role if it exists. Otherwise null.
- visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in ( true | false )
- createdAt: An epoch timestamp in milliseconds when the role was created.
- updatedAt: An epoch timestamp in milliseconds when the role was updated, if it exists. Otherwise null.
pageInfo: Pagination info
- itemCount: The number of items on this page.
- size: The size of the page, i.e. the number of items per page.
- hasNext: Indicates if there are more pages.
- marker: The marker that was used for this page.
- nextMarker: The marker that should be used to get the next page.
Example Response

{
  "roles": [
    {
        "visibleInSubdomains": true,
        "domainId": "root",
        "updatedAt": 1663770475385,
        "createdAt": 1663770471750,
        "description": "System role for legacy read access. This role cannot be changed.",
        "id": "readrole",
        "name": "Read"
    },
    {
        "visibleInSubdomains": true,
        "domainId": "root",
        "updatedAt": 1663770475329,
        "createdAt": 1663770471760,
        "description": "System role for legacy read-write access. This role cannot be changed.",
        "id": "readwriterole",
        "name": "ReadWrite"
    }
  ],
  "pageInfo": {
    "itemCount": 2,
    "size": 2,
    "hasNext": true,
    "marker": null,
    "nextMarker": "eyJlbnRpdHlUeXBlIjoiUm9sZS1yZWFkd3JpdGVyb2xlIiwicGFydGl0aW9uS2V5IjoiUm9sZXMifQ=="
  }
}

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`			Returned if a query parameter does not fulfil requirements.

LIST_ROLE_PRIVILEGES

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role

Lists the privileges of a role.

API Endpoint: [GET]: /permissions/roles/{id}/privileges

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the role required

Response

An array of all privileges of the role.

id: The ID of the privilege.
roleId: The ID of the role that the privilege belongs to.
objectName: The privilege object that the privilege applies to.
domainId: The domain where the privilege applies. Included if the type of the privilege is regular.
type: The type of the privilege. ( regular | settings)
name: The name of the privilege.
create: Whether the privilege gives create privilege or not. ( 0 | 1)
read: Whether the privilege gives read privilege or not. ( 0 | 1)
update: Whether the privilege gives update privilege or not. ( 0 | 1)
delete: Whether the privilege gives delete privilege or not. ( 0 | 1)

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`ROLE_NOT_FOUND`	`id`	Returned if the role does not exist or is inaccessible.

LIST_ROLE_USERS

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role

Lists all users that have the specified role.

API Endpoint: [GET]: /permissions/roles/{id}/users

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

id: The ID of the role required

Query Parameters

size: The desired page size. (max 100) optional
marker: The marker to get the next page. Received in previous response. optional

Example request

GET: /permissions/roles/readrole/users?size=10&marker=someMarker

Response

userIds: An array of users that have the role.
pageInfo: Pagination info
- itemCount: The number of items on this page.
- size: The size of the page, i.e. the number of items per page.
- hasNext: Indicates if there are more pages.
- marker: The marker that was used for this page.
- nextMarker: The marker that should be used to get the next page.

Example Response

{
  "userIds": [
    "95fde93a-aa8c-4b77-8089-a8a59e1ae923",
    "9bb33984-e3c9-448a-896d-ed30f6ce4d50",
    "b04b508a-547a-425f-9320-85600996ee37",
    "fe0a7d42-a43c-4b7b-b507-a8a3ddd23934",
    "217dd12a-83c2-46d4-bcb5-7861d6952aef",
    "f0e15f7c-686c-4500-9a98-fe580adee910",
    "0d4c1007-7189-4717-9053-2cd680803998",
    "5b78cedd-a48e-4494-b82f-3f29a19eb1e6",
    "0754234d-dd56-4dba-96f5-605965f4e504",
    "21b1e6d1-963e-4cc9-abe2-4e382c54b563"
  ],
  "pageInfo": {
    "itemCount": 10,
    "size": 10,
    "hasNext": true,
    "marker": "eyJlbnRpdHlUeXBlIjoiVXNlci05NWZkZTkzYS1hYThjLTRiNzctODA4OS1hOGE1OWUxYWU5MjMiLCJwYXJ0aXRpb25LZXkiOiJyZWFkcm9sZSJ9",
    "nextMarker": "eyJlbnRpdHlUeXBlIjoiVXNlci0yMWIxZTZkMS05NjNlLTRjYzktYWJlMi00ZTM4MmM1NGI1NjMiLCJwYXJ0aXRpb25LZXkiOiJyZWFkcm9sZSJ9"
  }
}

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`ROLE_NOT_FOUND`	`id`	Returned if the role does not exist or is inaccessible.

ADD_USER_TO_ROLE

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role or on a subdomain if the role is visible in subdomains
Required privilege: Users.UPDATE on the domainName of the user

Adds a user to a role, giving the user the privileges specified in the role.

If a role gives the user special IoT privileges (for example, permissions to subscribe to MQTT topics on another domain), the corresponding IoT policies are attached to the user’s Cognito IdentityId on the next login. A user can have a maximum of 7 IoT privileges at a time.

API Endpoint: [POST]: /permissions/roles/{roleId}/users

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

roleId: The ID of the role to which the user will be added required

Body

userId: The ID of an existing user to be added to the role required

Example payloads

{
  "userId": "95fde93a-aa8c-4b77-8089-a8a59e1ae923"
}

Response

userId: The ID of the user that was added to the role
roleId: The ID of the role to which the user was added
policyIsAttached: true if the role permits special IoT policies and those policies were attached successfully at runtime. Otherwise, false

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`NOT_AUTHORIZED_DOMAIN`			Returned if the user is not authorized for domain of target user.
`INVALID_ARGUMENTS`	`roleId`	`userId`	Returned if a parameter does not fulfil requirements.
`USER_HAS_ROLE`			Returned if the target user already has the role.
`USER_HAS_TOO_MANY_ROLES`			Returned if the target user will have a list of roles exceeding 2048 characters.
`ROLE_NOT_FOUND`	`roleId`		Returned if the specified role could not be found or is inaccessible.
`POLICY_LIMIT_EXCEEDED`			Returned if the target user would have too many iot policies attached.

REMOVE_USER_FROM_ROLE

Required role: ReadWrite
Required privilege: Permissions.READ on the domainId of the role or on a subdomain if the role is visible in subdomains
Required privilege: Users.UPDATE on the domainName of the user

Removes a user from a role, removing the privileges granted by that role.

If a role provided the user special IoT privileges (for example, permissions to subscribe to MQTT topics on another domain), the corresponding IoT policies are removed from the user’s Cognito IdentityId on the next login. A user can have a maximum of 7 IoT privileges at a time.

API Endpoint: [DELETE]: /permissions/roles/{roleId}/users/{userId}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path Variables

roleId: The ID of the role from which the user will be removed required
userId: The ID of the user to be removed from the role required

Response

On successful execution, this action returns an empty JSON object.

Errors

Key	Params	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`NOT_AUTHORIZED_DOMAIN`		Returned if the user is not authorized for domain of the target user.
`INVALID_ARGUMENTS`	`roleId`, `userId`	Returned if a parameter does not fulfil requirements.
`USER_DOES_NOT_HAVE_ROLE`		Returned if the target user does not have the role.
`ROLE_NOT_FOUND`	`roleId`	Returned if the role could not be found or is inaccessible.

GET_METADATA

Required role: None
Required privilege: None

Get information about available privilege object names and their requirements.

API Endpoint: [GET]: /permissions/metadata

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Response

availableObjectNames[]: An array with all available privilege object names
<a privilege object name>:
- create: true if operation create is available for the privilege object, false otherwise.
- read: true if operation read is available for the privilege object, false otherwise.
- update: true if operation update is available for the privilege object, false otherwise.
- delete: true if operation delete is available for the privilege object, false otherwise.
- domainId: true if a domain is required. false if it is forbidden.
- oneHasToBeSet[]: An array containing create/read/update/delete. At least one of them has to be set to 1.
- allHasToBeSet[]: An array containing create/read/update/delete. All has to be set to 1.

Response example

{
  "availableObjectNames": ["Users"],
  "Users": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true,
    "domainId": true,
    "oneHasToBeSet": ["create", "read", "update", "delete"],
    "allHasToBeSet": []
  }
}