User Role Permissions for APIs

July 12, 2022 18:41 Updated

This article provides guidance on API access by API endpoint and Manage role-based permissions. Access affects both the objects that can be requested as well as the objects that are returned when making API requests. The API permissions follow the below guidelines:

Users cannot get or post to object properties for objects to which the user has no access.
Users can only get metadata and aggregate energy consumption data for objects to which the user has full or partial access. For a description of full or partial access, refer to User Role Permissions.
1. Name
2. Object ID
3. Description, etc.
Users can only post object properties for objects to which the user has full access.
Users can get all object property data only for objects to which they have full access.
1. Sensor Details
2. Occupancy state
3. Device location
4. Energy (non-aggregate)
5. Applied profile
6. Scenes
7. etc.

403 Access Denied Message:

Access Denied! The user doesn't have the required permissions to access this 'object'

The warning message is displayed if the user doesn't have access based on role or access to the referenced object.

The object is defined by the structure of the API and the ID entered in either the API URI or the body of the request, if applicable. For example, if a user sent a campus_Id to which the user had no access in the 'GET All Buildings' API request, the user would receive a '403 Error' as the response. This is because the user does not have the required permissions to access this campus.

If the user has the option of making a request against two or more object types (e.g. floor or organization), the 403 Error message will use the object type of the object passed in the request (e.g., The 'GET All Scenes' API allows a user to pass either an organization_Id or floor_Id in the request. The error message will use either 'organization' or 'floor' based on which object_Id type is used by the user).

Energy and Environment APIs

For a description of full or partial access, refer to User Role Permissions.

Object_IDs allowed for a given API reflects the access to that resources required by a user in order to avoid a 403 error or for data to be returned. For example, a user can make a request to 'Get All Areas' for a floor to which they only have partial access (access to some, but not all areas on a floor), and the API response will only contain areas to which the user has been granted full access.

API Name

Admin

Auditor

Employee

Facilities Admin

BACnet

Object_ID Allowed (Request/Response)

Org

campus

Bldg

Floor

Area