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\ select one of your networks select one of your networks note that the list of features available to your applications depends on your access level in the selected network once the network is selected, you will be directed to the admin panel home screen, which looks like this go to settings > applications and select add application 5\ enter an application name and description, and select the features which your application needs to access according to the best security practices, it is recommended that you select only the features which correspond to the bsn cloud api methods that the related application actually uses for information about what scopes are required for each api call, see the feature access docid\ uu zupqkquf54rpi79xl1 and bsn cloud main apis docid\ goemci9nmvgakttr5qcjs documentation 6\ click the save button the new client id and secret will be displayed 7\ 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 note that according to rfc6749 section 4 4 2 , the issued client credentials must be provided using the "basic" authentication scheme in base64 format (as in the examples below) http get access token post https //auth bsn cloud/realms/bsncloud/protocol/openid connect/token content type application/x www form urlencoded authorization basic \[base64 encoded clientid and secret] 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 each application you register has access to all the networks of which you are currently a member, so every time you obtain an access token, the next step is to select the network which you want to access in the scope of this session for this purpose, you need to call the "put /2022/06/rest/self/session/network/" method, provide the access token issued in the previous step, and the name or identifier of the selected 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 once the network is selected, the current application has access to all of its resources but is limited by the permissions of the user who registered it, as well as features selected during registration be aware that every time an application issues a new access token, the target network needs to be selected again if the permissions of a user who registered a given application get changed or this user gets removed from the target network, the resources available to a given application change accordingly 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