ON THIS PAGE
The BSN REST API uses the OAUTH 2.0 framework to handle client authentication. This page describes how to build token authorization for BSN into a client application.
Authorization Workflow
These steps outline how a client application should carry out authorization with the BSN REST API:
- The client application makes a POST call to the
/Token/
endpoint. The POST body includes, among other parameters, ausername
andpassword
pair entered by the user.- If the user entered the network name along with his or her username and password, the client application includes the network name in the
username
(e.g."username=exampleNetwork/exampleUser@brightsign.biz"
). Otherwise, the network will need to be specified in a second POST call (see step 2a below).
- If the user entered the network name along with his or her username and password, the client application includes the network name in the
- If the credentials are valid, the server returns code 200 with a response body that includes
access_token,
expires_in
, andrefresh_token
values.- If a network name was not specified in step 1, the response body will also include a
networkNames
array that lists networks associated with the specifiedusername
. 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 theusername
(e.g."username=exampleNetwork/exampleUser@brightsign.biz"
).
- If a network name was not specified in step 1, the response body will also include a
- If less than half of the
expires_in
time has elapsed (in seconds), and the client application has retained theaccess_token
value in local storage, it includes theaccess_token
in the header of each request to a BSN endpoint.- If more than half of the
expires_in
time has elapsed, or if theaccess_token
is not located in local storage, the client application makes a POST call to the/token/
endpoint with therefresh_token
value. - If the
refresh_token
is not located in local storage, or if theexpires_in
time has elapsed (indicated by a 401 return from the server), 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.
- If more than half of the
Note
The expires_in
value may be changed on the server at any time, or it may be randomized on each authentication return. Therefore, the token expiration time should not be hardcoded on the client application; the application should be able to calculate token-refresh intervals on every return.
Example Requests and Responses
Person Authentication Request
POST https://ast.brightsignnetwork.com/2017/01/REST/Token HTTP/1.1 Host: ast.brightsignnetwork.com Content-Type: application/www-form-urlencoded Content-Length: 158 Accept: application/xml grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=exampleUser@brightsign.biz&scope=self
Person Authentication Response – Success
HTTP/1.1 200 OK Server: nginx/1.8.0 Date: Fri, 03 Feb 2017 23:02:00 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 688 Connection: keep-alive Vary: Accept-Encoding Cache-Control: no-cache Pragma: no-cache Expires: -1 Access-Control-Allow-Origin: * { "access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I", "token_type":"bearer", "expires_in":899, "refresh_token":"ee6c055a441047e99e5e2c3dde63fa4c", "scope":"Self", "userLogin":"authtest@brightsign.biz", "personId":13898, "networkNames":"AuthenticationTest1,AuthenticationTest2,AuthenticationTest3", ".issued":"Fri, 03 Feb 2017 23:02:00 GMT", ".expires":"Fri, 03 Feb 2017 23:17:00 GMT" }