Main API version 2020/10

overview 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 urls and endpoints the base url for the bsn cloud main rest api, version 2020/10, is https //api bsn cloud/2020/10/rest endpoints are appended to this base url trailing slashes can be used on bsn cloud endpoints but are optional (for example, /presentations/ ) authentication workflow the bsn cloud authentication process uses access credentials to produce a token which is then used to control access to all bsn cloud resources in your network the authentication workflow is based on the oauth2 protocol ( rfc6749 https //datatracker ietf org/doc/html/rfc6749 ), but the bsn cloud implementation has some customizations in bsn cloud, we distinguish person, user, and network entities the person entity is the representation of a given customer, a network is a representation of a company, and a user entity is an instance of a person that is associated with a single network a customer, represented by a person, may have only one user in every network but networks include one or more users who are associated with different customers the person entity (2020/10) docid\ ad1cnhugxxwibzw9x8v2l and user entity (2020/10) docid\ jirqabyicrjavih3z4zeq authentication workflows are separate because person authentication has a scope limit when you authenticate as a person in bsn cloud, you are authenticated with a limited set of features (for example, entering personal information, editing your profile, and creating a network) if you have a network or create a network, you can then authenticate as a user of that network once you are authenticated as a user, you can see which other networks you belong to or switch to person management and authenticate as a different user if you already have your network information, you can enter the network name/email address information for the username (for example, test/anon\@http //brightsign biz ), to skip authenticating as a person and just authenticate as a user authenticating as a person the person authentication response lists all the networks to which the person belongs and their statuses when the customer is on the brightauthor\ connected sign in page and enters their login and password, this response can be used to fill the list of networks in the dropdown so the user does not need to log separately to each network request information the self token has limited scope and can only be used to access the /self/ endpoint (which then allows you to authenticate as a user) the client application makes a post call to the /token/ endpoint with the following body grant type required required the type of grant being presented in exchange for the access token this value must be set to "password" client id required required the name of the application to authenticate any client application implemented by a customer must specify its readable name, which should be unique among client applications this property value accepts all client applications except those which are explicitly restricted client secret required required a global unique identifier for the application that is to be authenticated any client application implemented by a customer must specify a global unique identifier for their application, but this property value does not require registration username required required set this to your email address (when authenticating as a person) password required required the password associated with the username response information if the credentials are valid, the server returns code 200 with the following response body token type the oauth 2 0 token type, which will be returned as "bearer" access token the access token refresh token the token to use for re authentication when more than half of the expires in time period has elapsed expires in the lifetime (in seconds) of the authorization token person an array which contains the following information id the unique identifier for the person login the login email associated with the person firstname the first name of the person lastname the last name of the person users an array which contains the following information for each network associated with the user id the user id on the network role an array which contains the following information id the unique identifier for the role name the name of the role (for example "administrators") status whether the network is enabled or disabled network an array of information about the network entity id the unique identifier for the network name the name of the network status the network status (for example, "active" or "suspended") subscription level whether the network is "content" or "control" startdate the start date of the subscription enddate the end date of the subscription scope lists the scope granted by the token a successful response will include the self value only (for example, "bsn api self") issued 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 the date and time the authorization/refresh token expires (formatted as "\[3 letter weekday], dd mmm yyyy hh\ mm\ ss \[3 letter timezone]") 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 is incorrect") person oauth2 token renewal request information when the oauth access token is about to expire, or if you want profile changes to take effect, you can call the post/token method with the following parameters grant type required required the type of grant being presented in exchange for the access token this value must be set to "refresh token" client id required required the name of the application to authenticate any client application implemented by a customer must specify its readable name, which should be unique among client applications this property value accepts all client applications except those which are explicitly restricted client secret required required a global unique identifier for the application that is to be authenticated any client application implemented by a customer must specify a global unique identifier for their application, but this property value does not require registration refresh token required required the refresh token issued to a user as the result of a previous authentication workflow response information if the refresh token is valid, the server returns code 200 with the following response body token type the oauth 2 0 token type, which will be returned as "bearer" access token the access token refresh token the resulting refresh token may be different than the one provided in the request, if the remaining time is fifty percent or less, or if the token ttl (time to leave) in the person profile has changed expires in the lifetime (in seconds) of the authorization token person an array which contains the following information id the unique identifier for the person login the login email associated with the person firstname the first name of the person lastname the last name of the person users an array which contains the following information for each network associated with the user id the user id on the network role an array which contains the following information id the unique identifier for the role name the name of the role (for example "administrators") status whether the network is enabled or disabled network an array of information about the network entity id the unique identifier for the network name the name of the network status the network status (for example, "active" or "suspended") subscription level whether the network is "content" or "control" startdate the start date of the subscription enddate the end date of the subscription scope lists the scope granted by the token a successful response will include the self value only (for example, "bsn api self") issued 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 the date and time the authorization/refresh token expires (formatted as "\[3 letter weekday], dd mmm yyyy hh\ mm\ ss \[3 letter timezone]") 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 is incorrect") authenticating as a user request information the client application should then make a post call to the / token/ endpoint before the self token expires this endpoint, which grants access to a particular network and has more scope, returns a bearer token which allows you to perform operations in a network based on your role permissions grant type required required the type of grant being presented in exchange for the access token this value must be set to "password" client id required required the name of the application to authenticate any client application implemented by a customer must specify its readable name, which should be unique among client applications this property value accepts all client applications except those which are explicitly restricted client secret required required a global unique identifier for the application that is to be authenticated any client application implemented by a customer must specify a global unique identifier for their application, but this property value does not require registration username required required this is set to network name and email address (for example, test/anon\@http //brightsign biz ) after you have received the self token and are authenticating as a user password required required the password associated with the username scope optional optional this is an optional parameter if it is empty the server will issue a token with complete scope if it is specified, the server will check the user authorization for the scope and either apply the scope if the user has it or return an error if they do not see this rfc page https //datatracker ietf org/doc/html/rfc6749#section 3 3 for more information response information if the credentials are valid, the server returns code 200 with the following response body token type the oauth 2 0 token type, which will be returned as "bearer" access token the access token refresh token the token to use for re authentication when more than half of the expires in time period has elapsed expires in the lifetime (in seconds) of the authorization token user an array which contains the following information for the specified network associated with the user id the user id on the network role an array which contains the following information id the unique identifier for the role name the name of the role (for example "administrators") status whether the network is enabled or disabled network an array of information about the network entity id the unique identifier for the network name the name of the network status the network status (for example, "active" or "suspended") subscription level whether the network is "content" or "control" startdate the start date of the subscription enddate the end date of the subscription scope lists the scope granted by the token a successful response will return one of the following scope levels user in network with "content" subscription level "player bsn ui main bsn api self bsn api main bsn api upload" user in network with "control" subscription level "player bdeploy bsn api self bsn api main devices" devices in network with "content" subscription level "bdeploy bsn api device" devices in network with "control" subscription level "bdeploy bsn api device registration bsn api device status bsn api device echo" issued 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 the date and time the authorization/refresh token expires (formatted as "\[3 letter weekday], dd mmm yyyy hh\ mm\ ss \[3 letter timezone]") 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 is incorrect") user oauth2 token renewal request information when the oauth access token is about to expire, or if you want profile changes to take effect, you can call the post/token method with the following parameters grant type required required the type of grant being presented in exchange for the access token this value must be set to "refresh token" client id required required the name of the application to authenticate any client application implemented by a customer must specify its readable name, which should be unique among client applications this property value accepts all client applications except those which are explicitly restricted client secret required required a global unique identifier for the application that is to be authenticated any client application implemented by a customer must specify a global unique identifier for their application, but this property value does not require registration refresh token required required the refresh token issued to a user as the result of a previous authentication workflow username optional optional may be specified in order to switch between networks during token renewal response information if the refresh token is valid, the server returns code 200 with the following response body token type the oauth 2 0 token type, which will be returned as "bearer" access token the user access token refresh token the resulting refresh token may be different than the one provided in the request, if the remaining time is fifty percent or less, or if the token ttl (time to leave) in the user profile has changed expires in the lifetime (in seconds) of the authorization token user an array which contains the following information for the specified network associated with the user id the user id on the network role an array which contains the following information id the unique identifier for the role name the name of the role (for example "administrators") status whether the network is enabled or disabled network an array of information about the network entity id the unique identifier for the network name the name of the network status the network status (for example, "active" or "suspended") subscription level whether the network is "content" or "control" startdate the start date of the subscription enddate the end date of the subscription scope lists the scope granted by the token a successful response will return one of the following scope levels user in network with "content" subscription level "player bsn ui main bsn api self bsn api main bsn api upload" user in network with "control" subscription level "player bdeploy bsn api self bsn api main devices" devices in network with "content" subscription level "bdeploy bsn api device" devices in network with "control" subscription level "bdeploy bsn api device registration bsn api device status bsn api device echo" issued 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 the date and time the authorization/refresh token expires (formatted as "\[3 letter weekday], dd mmm yyyy hh\ mm\ ss \[3 letter timezone]") 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 is incorrect") upload api endpoints the upload api, which consists of multiple endpoints, is based on the openapi specification 2 0 ( https //swagger io/specification/v2/ ) this specification is machine readable so there is no need to manually upload the api client to create clients, find a generator which accepts this specification and will create a proxy class, with all appropriate methods, on your chosen platform and in your chosen language to do this, download the machine readable yaml specification at https //nam04 safelinks protection outlook com/?url=https%3a%2f%2fapi bsn cloud%2fupload%2f2019%2f03%2frest%2foas%2f\&data=05%7c01%7csmulqueen%40brightsign biz%7c0e158b6db7294b0fb48108da23d8ccee%7c8fbcdf641ab847cebdc743e23b04fb3c%7c0%7c0%7c637861711331602708%7cunknown%7ctwfpbgzsb3d8eyjwijoimc4wljawmdailcjqijoiv2lumziilcjbtii6ik1hawwilcjxvci6mn0%3d%7c3000%7c%7c%7c\&sdata=wdqc7%2bf8%2fg%2fqgtsfwwd4hbdr7yazsptcpkycgyydqa4%3d\&reserved=0