Main REST HTTP API version 2017/01
This page / section pertains to BrightSign Network (often abbreviated BSN), our legacy cloud platform. Our latest cloud platform is BSN.Cloud. Development of BSN has largely ceased and the platform will eventually be deprecated and replaced with BSN.Cloud.
BrightSign API structures operations and services are based on the REST principles. This approach allows you to group your data by resources, and for each resource, define a list of operations. The REST style is commonly used for create, read, update, and delete (crud) operations.
This documentation describes request and response entities. See Basic Rules & ConventionsBasic Usage Rules and Conventions for more info.
URLs and Endpoints
The base URL for the BrightSignNetwork.com Main REST API, version 2017/01, is https://api.brightsignnetwork.com/2017/01/REST/.
Endpoints are appended to this base URL. Except for the /Token endpoint, all BSN endpoints accept trailing slashes (for example, /Presentations/ ). Query strings that are appended to endpoint URLs (for example, "?filter", "?sort") must be URL encoded.
Authentication Workflow
The BrightSignNetwork.com authentication process uses access credentials to produce a token which is then used to control access to all BrightSignNetwork.com resources in your network.
The authentication workflow is based on the OAuth2 protocol (rfc6749). The BSN user model distinguishes between "persons" and "users":
- A "person" is tied to a single set of login credentials, but is not exclusively linked to any one network (each network is an independent set of users, files, presentations, etc.).
- A "user" is an instance of a person that is associated with a single network.
This user model allows persons who belong to multiple networks to log in to them using a single set of credentials. In many cases, it also requires two token-authentication requests, as described below.
To authorize a client application:
- Make a POST call to the /token endpoint which includes a username and password. You can enter the network name with the username (for example, exampleNetwork/[email protected]). If you do not, a network must be specified in step 2.
- If the credentials are valid, the server returns code 200 with a response body that includes access_token, expires_in, and refresh_token values. If a network name was not specified, the response will include the networks associated with the username. Select a network, which will be included in the username in the next POST call.
- If less than half of the expires_in time has elapsed and the client application has retained the access_token value in local storage, it includes the access_token in the "Authorization" header of each request to a BSN endpoint. The value of the "Authorization" header is specified as "Bearer {token_value}".
- 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 will make a POST call to the /token endpoint with the refresh_token value.
- 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 will indicate that access to the BSN connection has been dropped (without loss of unsaved user data) and prompt you to reenter access credentials and returns to step 1 of the authentication process.
- 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 store the expires_in value along with the Access/Refresh token and calculate a new token-refresh interval on every return.
/Token
POST
Posts user credentials or a refresh token to the /Token endpoint (this endpoint does not accept a trailing slash). If the credentials are valid, the server returns an access/refresh token that is included with all other BSN REST calls for authentication.
Request Body
username: The BrightSignNetwork.com username. A network name can be appended (for example, exampleNetwork/[email protected]).
password: The password associated with the username.
network: The network to which the returned token should grant access. This entry can can be used for either the initial authentication request, or to switch to another network that the user belongs to on token renewal.
grant_type: The type of grant being presented in exchange for the access token. This value must be set to "password".
client_id: The client identifier. This value is currently not used by the server.
client_secret: The client secret. This value is currently not used by the server.
refresh_token: The refresh token to include when renewing the access token. When the refresh_token entry is included, the password does not need to be used.
Response Body
access_token string: The authorization token to use with endpoint calls until half of the expires_in time period has elapsed
token_type string: The OAuth 2.0 token type, which will always be returned as "bearer"
expires_in integer: The lifetime (in seconds) of the authorization token
refresh_token string: The token to use for re-authentication when more than half of the expires_in time period has elapsed.
scope string[]: An array that lists the scope granted by the token. A successful Person Authentication Response will include the "Self" value only, while a successful User Authentication Response will contain both "Full" and "Self" values.
userLogin string: The username included in the request body
userId integer: The user identifier, which may be used in subsequent requests. This entry is only returned for User Authentication Requests.
personId integer: The person identifier
networkNames string[]: An array of networks to which the person (i.e. the account associated with the login credentials) belongs. This entry is only returned for Person Authentication requests.
.issued string: The date and time the authorization/refresh token was issued (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")
.expires string: The date and time the authorization/refresh token expires (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")
Person Authentication Examples
Request Body
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://api.brightsignnetwork.com/2017/01/REST/token
Host: api.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&[email protected]&password=admin&scope=selfResponse Body
A successful response will include a HTTP status code of 200. Note that the response includes the networkNames list.
{
"access_token": "N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type": "bearer",
"expires_in": 899,
"refresh_token": "ee6c055a441047e99e5e2c3dde63fa4c",
"scope": "Self",
"userLogin": "[email protected]",
"personId": 13898,
"networkNames": "AuthenticationTest1,AuthenticationTest2,AuthenticationTest3",
".issued": "Fri, 03 Feb 2017 23:02:00 GMT",
".expires": "Fri, 03 Feb 2017 23:17:00 GMT"
}If the credentials are not valid, the server will return code 400 with the following response body:
- error: Returns the error status (for example, "invalid_request" or "invalid_grant")
- error_description: A description of the error (for example, "The specified Username or Password is incorrect")
User Authentication Examples
Request Body
The client application makes this authorization request when it has the network name, which can be 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://api.brightsignnetwork.com/2017/01/REST/token
Host: api.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/[email protected]&password=admin&scope=fullResponse Body
A successful response will include a HTTP status code of 200.
{
"access_token": "N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type": "bearer",
"expires_in": 899,
"refresh_token": "375671af51fa44fabb5b4a353d4f8488",
"scope": "Full,Self",
"networkName": "AuthenticationTest1",
"userLogin": "[email protected]",
"userId": 18537,
"personId": 13898,
"roleName": "Administrators",
".issued": "Fri, 03 Feb 2017 23:37:26 GMT",
".expires": "Fri, 03 Feb 2017 23:52:26 GMT"
}If the credentials are not valid, the server will return code 400 with the following response body:
- error: Returns the error status (for example, "invalid_request" or "invalid_grant")
- error_description: A description of the error (for example, "The specified Username or Password is incorrect")
Renew Access Token Examples
Request Body
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.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=375671af51fa44fabb5b4a353d4f8488Response Body
A successful response will include a HTTP status code of 200.
{
"access_token": "N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type": "bearer",
"expires_in": 899,
"refresh_token": "375671af51fa44fabb5b4a353d4f8488",
"scope": "Full,Self",
"networkName": "AuthenticationTest1",
"userLogin": "[email protected]",
"userId": 18537,
"personId": 13898,
"roleName": "Administrators",
".expires": "Sat, 04 Feb 2017 00:05:26 GMT",
".issued": "Fri, 03 Feb 2017 23:50:26 GMT"
}If the credentials are not valid, the server will return code 400 with the following response body:
- error: Returns the error status (for example, "invalid_request" or "invalid_grant")
- error_description: A description of the error (for example, "The specified Username or Password is incorrect")
Example API Call with Authorization
The access token is included in the "Authorization" header of each API request. The token value is prefixed with the "Bearer" specification.
GET https://api.brightsignnetwork.com/2017/01/REST/Devices/ HTTP/1.1
Accept-Encoding: gzip,deflate
Origin: https://localhost/
Authorization: Bearer 79ADEgjjEOpSOsgQ1kpqYL0O3R8vnh27q22ltp7hyTgTQPWxdjrHD
Host: api.brightsignnetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)Filtering Expressions
See Filtering Expressions in the Main API (2017/01)Filtering Expressions in the Main API (2017/01)
Upload Endpoints
See Upload Endpoints (2017/01) for more information about how to upload files to BrightSignNetwork.com.