REST Authentication

Like many REST frameworks, the BSN REST API uses a refresh-token system to handle client authentication. This page describes how to build token authorization for BSN into a client application.

Authorization Workflow

These steps outline how to carry out authorization with the BSN REST API:

1. The client makes a POST call to the /Token/ endpoint. The POST body includes, among other parameters, a username and password pair.
   1. If the user entered the network name along with his or her username and password, the network name is included in the username (e.g. "username=exampleNetwork/exampleUser@brightsign.biz"
2. If the credentials are valid, the server returns a code 200 with a response body that includes access_token, expires_in, and refresh_token values. 
   1. The response body includes a networkNames array that lists networks associated with the specified username. The client application provides the list of networks to the user and allows him or her to select one. It then makes a second POST to the /token/ endpoint with network name included in the username (e.g. "username=exampleNetwork/exampleUser@brightsign.biz").
3. If less than half of the expires_in time has elapsed (in seconds), and the client application has retained the access_token value in local storage, it includes the access_token in the header of each request to a BSN endpoint.
   1. If more than half of the expires_in time has elapsed, or if the access_token is not located in local storage, the client application makes a POST call to the /token/ endpoint with the refresh_token value.
   2. If the refresh_token is not located in local storage, the application indicates to the user that access to the BSN connection has been dropped (without loss of unsaved user data). It then prompts the user to enter access credentials again and returns to step 1 of the authentication process.