Main REST HTTP API version 2017/01

1 URLs and Endpoints
2 Authentication Workflow
- 2.1 /Token
- 2.2 Person Authentication Examples
- 2.3 User Authentication Examples
- 2.4 Renew Access Token Examples
- 2.5 Example API Call with Authorization
3 Filtering Expressions
4 Upload Endpoints

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 Usage Rules and Conventions for more information.

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/exampleUser@brightsign.biz). 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/exampleUser@brightsign.biz).

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&username=exampleUser@brightsign.biz&password=admin&scope=self

Response 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": "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"
}

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/exampleUser@brightsign.biz&password=admin&scope=full

Response Body

A successful response will include a HTTP status code of 200.

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

Response Body

A successful response will include a HTTP status code of 200.

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.

Filtering Expressions

See Filtering Expressions in the Main API (2017/01)

Upload Endpoints

See Upload Endpoints for more information about how to upload files to BrightSignNetwork.com.