Why Are Viewer Tokens Required?
A typical use case for the Plans JavaScript SDK is to present plans inside web pages.
If you were to use your API secret instead of a Viewer 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 your page’s javascript.
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 JavaScript SDK users from a worst case scenario, we require all Plans JavaScript SDK users to use Viewer Tokens.
How do Viewer Tokens solve this problem?
Viewer Tokens are base64 encoded parameters packaged with a SAS token.
SAS tokens are signatures of the parameters. These signatures are calculated with the HMAC-SHA256 algorithm using your API secret as a key.
Our servers validate the parameters against the included signature and reject requests with an invalid signature. This stops users editing Viewer Tokens to request 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 JavaScript SDK into applications that already have their own permissions systems.
Using Viewer Tokens to expire old viewers
In addition to having total control over what plans your users can access, you can also use Viewer Tokens to control the when with the expiry 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 Viewer Token for longer than you’d like them to. For example, you could construct Viewer Tokens 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 plans after 2 minutes - old Viewer Tokens served to them will have expired and you won’t be serving them any new ones.