Why Are SAS Tokens Required?

A typical use case for the Plans Static API is to present images of floorplans inside web pages.

For example, you might have a snippet like this that embeds an image of a floorplan into your web page:

...
<img
  width="640" height="360"
  src="https://api.locatrix.com/plans-static/v1/image?partner=cadr0g675rbk0fv03fm5fewz7
    &floor=flr_95kpvk552x7ue5xvb4f290a4q
    &format=png&w=640&h=360
    &expiry=2145916800
    &apikey=ADD_API_KEY_HERE
    &sas=ADD_SAS_TOKEN_HERE"
/>
...

If you were to add your API secret to the URL instead of a SAS token, you would be giving your users your API secret. The web page would be sent to the user’s browser, and they could view the source of the web page and see your API secret as part of the image’s URL.

This would allow your users to do anything that your API secret authorizes you to do, such as:

List all available clients/campuses/buildings/floors
Access all available plans that your API secret is authorized to access

In the best case, this may not be a problem if your users could already use your application to browse through every available plan.

In the worst case, this could completely bypass any kind of permissions system in your application that only allowed users to access specific plans.

To help protect all Plans Static API users from a worst case scenario, we require all Plans Static API users to use SAS tokens.

How do SAS tokens solve this problem?

SAS tokens are signatures of the URL’s query string parameters. These signatures are calculated with the HMAC-SHA256 algorithm using your API secret as a key.

Our servers validate URL parameters against the included signature and reject requests with an invalid signature. This stops users editing URLs to request images of different floorplans, as users can’t generate a valid signature without your API secret.

As a developer, this gives you total control over the floorplan/siteplans that your users can access and allows you to integrate the Plans Static API into applications that already have their own permissions systems.

Using SAS tokens to expire old URLs

In addition to having total control over what plans your users can access, you can also use SAS tokens to control the when with the expiry URL parameter.

This expiry parameter causes requests to fail after a given time, and is signed into the SAS token just like the other parameters. As a result, it is impossible for users to change the expiry time as they cannot generate a valid SAS token.

You can use this to ensure that users can’t use a given Plans Static API URL for longer than you’d like them to. For example, you could construct URLs that are only valid for 2 minutes and serve them to your users. Then, if you need to revoke a user’s access to your system you can be sure that the user will not have access to up-to-date plan imagery after 2 minutes - old URLs served to them will have expired and you won’t be serving them any new ones.