User Role Permissions for APIs

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:

  1. Users cannot get or post to object properties for objects to which the user has no access.

  2. 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.

  3. Users can only post object properties for objects to which the user has full access.

  4. 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 Sensor Plug load Switch group
Get Organization Details Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial/Partial              
Get Energy Manager Aggregate Energy Consumption Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial/Partial                
Get BACnet Health Yes_Access.gif     Yes_Access.gif   Full/Full              
Get All Campuses Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial  Partial            
Get All Buildings Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif   Partial Partial          
Get All Floors Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial     Partial        
Get Floor Plan Image Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial/Partial        
Get all Areas Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial  Full      
Get Area Energy Consumption Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full/Full      
GET Area Outage Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full/Full      
Get Gateway Details by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial/Partial        
Get Sensor Details Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif           Full/Full    
Get Sensor Details by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial   Full    
GET Fixture Dim Level by Floor
Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial   Full    
Get Sensor Location by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial    Full    
Get All Fixtures by Area Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif           Full  Full    
Get Sensor Profiles Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif           Full/Full    
Get Sensor Energy Consumption Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif           Full/Full    
Get Sensor Energy Consumption by Area Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full/Full      
Get Plugload Details Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif             Full/Full  
Get All Plugloads by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial      Full  
Get All Plugloads by Area Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full    Full  
Get Plugload Energy Consumption Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif             Full/Full  
Get Plugload Energy Consumption by Area Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full    Full  
Get Switch Groups Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial     Full        Full
Get Switch Scenes Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Full       Full/Full
Get Scene Light Levels for a Switch Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif               Full/Full
Get Sensor Energy Data by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial    Full    
Get Aggregate Sensor Energy Data by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial/Partial        
List Demand Response Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Partial/Partial              
Get all BLE Fixtures by Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Partial/Partial        
Set Emergency Yes_Access.gif       Yes_Access.gif Full              
Set Area Emergency Yes_Access.gif     Yes_Access.gif Yes_Access.gif         Full      
Assign Profile Yes_Access.gif     Yes_Access.gif             Full    
Set Plugload Status Yes_Access.gif   Yes_Access.gif Yes_Access.gif Yes_Access.gif             Full  
Apply Scene Yes_Access.gif   Yes_Access.gif Yes_Access.gif Yes_Access.gif               Full
Manual Override for Switch Group Yes_Access.gif   Yes_Access.gif Yes_Access.gif Yes_Access.gif       Full       Full
Auto Mode for a Fixture Yes_Access.gif     Yes_Access.gif             Full    
Set BLE Mode of Sensor Yes_Access.gif                   Full    
Manual Override for a Fixture Yes_Access.gif   Yes_Access.gif Yes_Access.gif Yes_Access.gif           Full    
Schedule Demand Response (DR) for Selected Facilities Yes_Access.gif     Yes_Access.gif Yes_Access.gif       Full        
Update Demand Response for Selected Facilities Yes_Access.gif     Yes_Access.gif Yes_Access.gif       Full        
Cancel Demand Response Yes_Access.gif       Yes_Access.gif Full              
Schedule Demand Response (DR) for all Facilities Yes_Access.gif       Yes_Access.gif  Full              
Update Demand Response for all Facilities Yes_Access.gif       Yes_Access.gif   Full              

Occupancy API

API Name                                          

Admin Auditor Employee Facilities Admin BACnet Org                Campus         Bldg     Floor               Area Sensor Plug load Switch Group
Get Area Occupancy Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Full/Full      
Get Area Occupancy for a Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif       Partial Full      
Get Real-time Desk Occupancy for a Floor Yes_Access.gif Yes_Access.gif Yes_Access.gif Yes_Access.gif         Partial   Full    

DALI Emergency Lighting API

API Name                                          

Admin Auditor Employee Facilities Admin BACnet Org                Campus         Bldg     Floor               Area Sensor Plug load Switch Group

Start the Functional or Duration Test for a Fixture

Driver Status to Normal (Stop Test)

Yes_Access.gif     Yes_Access.gif Yes_Access.gif           Full/Full    
Update Test Parameters for a Fixture Yes_Access.gif     Yes_Access.gif Yes_Access.gif           Full/Full    
Get the List of Emergency Fixtures by Floor Yes_Access.gif     Yes_Access.gif Yes_Access.gif           Full/Full    
Get Fixture Status by Fixture Yes_Access.gif     Yes_Access.gif Yes_Access.gif           Full/Full    
Get Driver Test Parameters by Fixture Yes_Access.gif     Yes_Access.gif Yes_Access.gif           Full/Full    

 

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

Article is closed for comments.