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 Params 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 Property 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 Property 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 Property 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 Params 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 Property 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 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 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 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 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 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 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 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 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": []
  }
}