REST Authentication

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.

Authentication 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, a username and password pair entered by the user.
1. 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 credentials are valid, the server returns code 200 with a response body that includes access_token, expires_in, and refresh_token values.
1. 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 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").
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, or if the expires_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.

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 calculate a new token-refresh interval on every return.

Example Requests and Responses

Person Authentication Request

The client application makes this authorization request when it does not have the network name. A successful response will include a list of network names.

POST https://brightsignnetwork.com/2017/01/REST/Token HTTP/
Host: 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&password=admin&scope=self

Person Authentication Response – Success

Note that the response includes the networkNames list.

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":"exampleUser@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"
}

Person Authentication Response – Failure, Invalid Credentials

HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:16:17 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 95
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *

{
"error":"invalid_grant",
"error_description":"The specified User ID or Password is incorrect."
}

User Authentication Request

The client application makes this authorization request when it has the network name, which can retrieved either from user entry or from a Person Authentication Request. Note that the response body includes the roleName parameter, which allows the client application to determine the permissions scope and available functionality for the user.

POST https://brightsignnetwork.com/2017/01/REST/
Host: ast.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 178
Accept: application/xml

grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=AuthenticationTest1/exampleUser@brightsign.biz&password=admin&scope=full

User Authentication Response – Success

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:37:26 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 823
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":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".issued":"Fri, 03 Feb 2017 23:37:26 GMT",
".expires":"Fri, 03 Feb 2017 23:52:26 GMT"
}

User Authentication Response – Failure, Invalid Credentials

HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:33:03 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 95
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *

{
"error":"invalid_grant"
,"error_description":"The specified User ID or Password is incorrect."
}

Renew Access Token Request

POST https://brightsignnetwork.com/2017/01/REST/
Host: ast.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 151
Accept: application/xml

grant_type=refresh_token&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&refresh_token=375671af51fa44fabb5b4a353d4f8488

Renew Access Token Response – Success

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:50:26 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 823
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":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".expires":"Sat, 04 Feb 2017 00:05:26 GMT",
".issued":"Fri, 03 Feb 2017 23:50:26 GMT"
}

Renew Access Token Response – Failure, Invalid Refresh Token

HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:55:43 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 87
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *

{
"error":"invalid_grant",
"error_description":"The specified Refresh Token is invalid."
}