ESAPI

View ESAPI documentation here.

The ESAPI is the entry point for using the Locatrix APIs. Use the ESAPI to navigate the client/campus/building/floor hierarchy, and retrieve plan codes and viewer tokens for use with the Plans APIs.

Get the Postman Collection here and the Postman Environment here.

Getting viewer tokens

Viewer tokens allow you to grant access to the plans within a client/campus/building/floor without allowing users to access anything else. They are signed using your API secret, so that end users can’t ask the viewer to load a plan they aren’t allowed to see. This is an extension of the exact same logic for SAS tokens used in the Plans Static API, however we have simplified the process so that tokens are generated on our servers using an API request, instead of requiring you to implement a specific algorithm on your server.

You can obtain viewer tokens on your server by calling the Locatrix ESAPI using:

• GET https://api.locatrix.com/esapi/api/v1/Floors/{floor code}
• GET https://api.locatrix.com/esapi/api/v1/Buildings/{building code}
• GET https://api.locatrix.com/esapi/api/v1/Campuses/{campus code}
• GET https://api.locatrix.com/esapi/api/v1/Clients/{client code}

Viewer tokens are labelled by their access level:

• The "allAreas" token will load the entire plan associated with the resource and allow users to see all areas of it. It does not permit access to any other plans.
• The "allAreasAndChildren" token is similar to the "allAreas" token, however it permits access to every plan associated with the resource and all of its children.

For example, the "allAreas" token associated with a campus will only allow you to load that campus’s site plan. However, the "allAreasAndChildren" token for that campus will grant you access to the site plan, as well as the floorplans of every floor in every building within the campus. Because only campuses and floors have plans directly associated with them, the "allAreas"token is not available for buildings and clients.

You should only use viewer tokens that grant users access to the resources that they need to see. If they only need to see two floors out of 50 in a building, you should get viewer tokens for those specific floors and use those, rather than using an "allAreasAndChildren" viewer token for the entire building and leaking information.

Be careful to ensure your use of viewer tokens is consistent with your application’s security model. If your app provides floor-level access control, use viewer tokens from individual floors. If your app provides building-level access control, then it’s OK to use viewer tokens for entire buildings.

In the future, we will provide additional access levels for only loading specific parts of the plan that an end user is allowed to see.

You can get viewer tokens on your server:

GET https://api.locatrix.com/esapi/api/v1/Client/clnt_vqk8dllmayur3r5tx6z3rerj4
==>
{
  "code": "clnt_vqk8dllmayur3r5tx6z3rerj4",
  "name": "Contoso Corporation",
  ...
  "viewerTokens": {
    "allAreas": null,
    "allAreasAndChildren": "djI6YWxsQXJlYXM6Y2xudF92cWs4ZGxsbWF5dXIzcjV0eDZ6M3Jlcmo0OnB0bnJfY2FkcjBnNjc1cmJrMGZ2MDNmbTVmZXd6NzoxNjIwMDg5NjE5LDI2YTgwYjFjLWI5MWUtYzkyNi02YTNiLWVhZGFjMDM3OWNlMyx1NmRCYlRzZXNwSFBDaTZjMVBydjl1Vzh0TzcyYjNzM1BDbXQ5MHhKeFNzJTNk",
    "expiry": "2020-09-16T15:42:05.3936024Z"
  }
}