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 which consists of the free bsn control tier and the paid bsn content tier 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 & conventions docid 4lfamzwnwhku35lvn3bhj 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 https //www w3schools com/tags/ref urlencode asp 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 https //datatracker ietf org/doc/html/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 { "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" } 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=375671af51fa44fabb5b4a353d4f8488 response 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" "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" } 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 filter expressions in the main api (2017/01) docid\ l8mfvfdghpy9xgiuquwcm upload endpoints see upload endpoints (2017/01) docid\ huqzpplhegjwcbwmz0iwz for more information about how to upload files to brightsignnetwork com