2025 API Usage Guide

brightsign’s authentication server supports single sign on (sso), multi factor authentication (mfa), and other standard protocols such as openid connect, oauth 2 0, and saml we have implemented the oauth2 “ client credentials flow ” to allow customers to self serve their credentials (client id and secret) and to allow for more granular control of what the resulting tokens can do, improving security client credentials are used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user for example, these credentials can be useful for background services that apply changes to the system in general rather than for a specific user api workflow this document describes the steps required use our apis along with code examples create client credentials to create new client credentials 1\ login into the bsn cloud admin panel at https //adminpanel bsn cloud https //adminpanel bsn cloud 2\ go to settings / applications and select add application 3\ enter an application name and description, and select one or more features that this application will be able to access for information about what scopes are required for each api call, see the bsn cloud main apis docid\ goemci9nmvgakttr5qcjs 4\ click the save button the new client id and secret will be displayed 5\ copy these values and store them securely, ideally in a password manager they will not be shown again after leaving this screen secrets expire every 180 days you should rotate them on or before they expire notes multiple applications can be created application name, description and permitted features can be edited or deleted secrets can be rotated (see below) get access token to make any api calls to bsn cloud an access token must be obtained from the token endpoint https //auth bsn cloud/realms/bsncloud/protocol/openid connect/token http get access token post https //auth bsn cloud/realms/bsncloud/protocol/openid connect/token content type application/x www form urlencoded authorization basic \[clientid] \[clientsecret] accept application/json grant type=client credentials typescript get access token const clientid = '\[clientid]'; const clientsecret = '\[clientsecret]'; const clientcredentials = buffer from(`${clientid} ${clientsecret}`) tostring('base64'); const request = formbody({ 	grant type 'client credentials' }) tostring(); const headers = { 	'content type' 'application/x www form urlencoded', 	'authorization' `basic ${client credentials}`, 	'accept' "application/json", }; const response = await axios post(`https //auth bsn cloud/realms/bsncloud/protocol/openid connect/token`, request, { headers }); return response data as { accesstoken string }; expected response codes code description 200 200 ok ok 401 401 unauthorized invalid credentials unauthorized invalid credentials notable response data property description access token access token to be used with api calls until expiry expires in time to expiry of the access token scope permitted scopes set network after obtaining an access token, a network must be selected by making a call to the following endpoint https //api bsn cloud/2022/06/rest/self/session/network http select network by id put https //api bsn cloud/2022/06/rest/self/session/network content type application/json authorization bearer \[accesstoken] accept application/json { "id" \[networkid] } http select network by name put https //api bsn cloud/2022/06/rest/self/session/network content type application/json authorization bearer \[accesstoken] accept application/json { "name" "\[networkname]" } typescript select network by id or name const network = "\[networkid|networkname]"; const body = 	isnumber(network) ? { id network } 	isstring(network) ? { name network } 	network; return await this put(`2022/06/rest/self/session/network`, body, \["vnd bsn error"]); expected response codes code description 204 204 ok no content ok no content 400 400 bad request network does not exist bad request network does not exist 401 401 unauthorized access token has expired unauthorized access token has expired use the api after a network has been selected, the bsn cloud api can be used within the scope permitted for that token you must provide the access token with every api call when a 401 error code is received, this indicates that the access token has expired you should then repeat the above process to obtain a new access token and set a network in some scenarios it might prove optimal to get a new access token prior to it expiring you can use the expires in value returned in the get access token payload, to calculate the expiry time and prefetch a new token ahead of time if a 403 error code is received, this indicates that your access token is not authorized to make this request, and you should check the application scopes are correctly specified expected response codes code description 200 200 ok ok 401 401 unauthorized access token has expired unauthorized access token has expired 403 403 forbidden access token is not permitted to make the request forbidden access token is not permitted to make the request rotating client secrets client secrets are expired every 180 days secrets can be rotated more often for additional security you can rotate the secrets automatically via the api, or manually via the user interface if a secret is suspected to be compromised, you should immediately rotate it by using the rotate secret option in the user interface rotating will return a new secret immediately, this should be stored securely the old secret will continue to work for a limited time and it should be used until it fails, and then switch to the new secret http rotate client secret to rotate the client secret via the api the following method is provided replace {id} with the application id, not the client id post https //api bsn cloud/2022/06/rest/self/applications/{id}/secret/ content type application/json authorization bearer \[accesstoken] accept application/json expected response codes code description 200 200 success existing client secret was invalidated and new secret is provided in response success existing client secret was invalidated and new secret is provided in response 401 401 unauthorized access token has expired unauthorized access token has expired 403 403 forbidden access token is not permitted to make the request forbidden access token is not permitted to make the request faq how do i know what scopes to allocate to my application? for information about what scopes are required for each api call, see the bsn cloud main apis docid\ goemci9nmvgakttr5qcjs how long does the new access token lifetime last? 5 minutes 30 seconds how long does network session lifetime last? 24 hours are refresh tokens supported? no, refresh tokens not supported with the oauth2 “ client credentials flow ” what if i suspect my client secret has been compromised? you should use the admin panel to rotate the secret and then continue to use the old secret until it no longer works, then use the new secret are there other ways to handle a compromised client secret? yes, you can simply delete the application this will destroy the existing client id and secret you can create another application to obtain a new client id and secret do client secrets expire? yes, client secrets expire every 180 days you should rotate them automatically or manually on or before they expire further information for further information contact support\@brightsign biz mailto\ support\@brightsign biz