Permissions

A permission defines a resource access policy for one principal.

Endpoints

The Permission object

  • idinteger

    Unique ID assigned at time of creation.

  • projectIdinteger

    Project that this permission belongs to.

  • statementTypestring| options are principalBased

    Statement type

  • principalTypestring| options are user

    Principal type

  • principalIdinteger

    Principal ID (e.g., user ID)

  • resourceTypestring| options are all, users, homes, entityClass, entity, alertRules, projectLogs, projectAlerts, devices

    Resource type

  • resourceIdentifierstring

    Resource ID (e.g., user ID, entity ID). * is used to represent all

  • resourceScopestring| options are self, selfWithDescendants

    Resource scope. Only Entity supports resource scope.

  • actionsarray

    Allowed/denied actions

  • effectstring| options are allow, deny

    Access policy

  • subResourcesarray

    Array of sub-resource permissions

The Sub-resource Permission object

  • resourceTypestring| options are userLog, homeKeyValue, homeLog, homeDevice, homeSmartModuleREST, homeEvent, homeAlert, entityMetric, entityBlob, entityEvent, entityAlert

    Sub-resource type

  • actionsarray

    Allowed/denied actions

  • effectstring| options are allow, deny

    Access policy

Get permissions

Endpoint
get /permissions
Description

Get a list of permissions of a resource (by using the resourceId parameter), or permissions of a user (by using the userId parameter). Either the resourceId or userId must be specified.

Query Parameters

  • projectId

    integer

    required

    Return permissions of the specified project.

  • userId

    integer

    Return permissions of the user.

  • resourceType

    string

    Return permissions of the resource. The resourceId must be also specified.

  • resourceId

    integer | string

    Return permissions of the resource. The resourceType must be also specified.

  • skip

    integer

    Number of permissions to skip over.

  • limit

    integer

    Maximum number of permissions to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key with "Admin" privileges.

Response
  • 200Successful retrieval of list of permissions.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

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

Create a permission

Endpoint
post /permissions
Description

Create a permission. If the request is made by a user, the user must have a managePermissions permission on the resource.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key with "Admin" privileges.

Request Body

  • actions

    array

    required

    Allowed/denied actions

  • effect

    string

    required

    Access policy

    Options are allow, deny

  • subResources

    array

    Array of sub-resource permissions

Response
  • 201Successfully created a new permission.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "projectId": 2,
  "principalType": "user",
  "principalId": 1,
  "resourceType": "all",
  "resourceIdentifier": "*",
  "statementType": "principalBased",
  "effect": "allow"
}

Response Body Sample

{
  "id": 15,
  "projectId": 2,
  "statementType": "principalBased",
  "principalType": "user",
  "principalId": 1,
  "resourceType": "all",
  "resourceIdentifier": "*",
  "effect": "allow"
}

Get a permission

Endpoint
get /permissions/{permissionStatementId}
Description

Return the permission with the specified ID.

Path Parameters

  • permissionStatementId

    integer

    required

    The unique ID for a specified permission.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key with "Admin" privileges.

Response
  • 200Successfully retrieved permission with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested permission does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 13,
  "projectId": 2,
  "statementType": "principalBased",
  "principalType": "user",
  "principalId": 2,
  "resourceType": "homes",
  "resourceIdentifier": "2",
  "actions": [
    "read",
    "create",
    "update",
    "delete",
    "managePermissions"
  ],
  "effect": "allow"
}

Update a permission

Endpoint
patch /permissions/{permissionStatementId}
Description

Update the permission with the specified ID. Only the actions, effect, and subResources field of the permission can be changed.

Path Parameters

  • permissionStatementId

    integer

    required

    The unique ID for a specified permission.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key or a project API key with "Admin" privileges.

Request Body

  • actions

    array

    The new actions.

  • effect

    string

    The new policy.

  • arrayPermissionSubResources

    json

    The new sub-resource policies.

Response
  • 204Successfully updated permission with specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested permission does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "actions": [
    "managePermissions"
  ],
  "subResources": [
    {
      "resourceType": "homeKeyValues",
      "actions": [
        "update"
      ],
      "effect": "allow"
    }
  ]
}

Delete a permission

Endpoint
delete /permissions/{permissionStatementId}
Description

Delete the permission with the specified ID.

Path Parameters

  • permissionStatementId

    integer

    required

    The unique ID for a specified permission.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key or a project API key with "Admin" privileges.

Response
  • 204Successfully deleted permission with the specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required permission does not exist or is not accessible.
  • 409The permission cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.