Introduction

BrightSign changed the authentication server used by BSN.Cloud in 2024 to be able to support Single Sign-On (SSO), Multi-Factor Authentication (MFA), and other standard protocols such as OpenID Connect, OAuth 2.0, and SAML.

Existing users of our APIs use the OAuth2 “Resource Owner Password Flow” to obtain Access and Refresh tokens. Those tokens are used in each API call to get data.

As a result of changing the authentication server, 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.

The existing “Resource Owner Password Flow” approach will not work with the new “Client Credentials Flow” workflow, so all customers that directly use our APIs must update their existing code and scripts.

We will be decommissioning the legacy BSN.Cloud API token endpoint, some of our older APIs, and older versions of BrightAuthor:connected later in 2025 to give customers time to make the required changes. The exact date of decommissioning will be communicated separately.

BrightAuthor:connected Version Compatibility

Customers must upgrade to BrightAuthor:connected version 1.59 or later to continue to be able to login to BSN.Cloud.

BSN.Cloud API Deprecations

The following APIs and API endpoints should no longer be used. Alternative implementations are provided, as shown in the table below. The legacy endpoints will be decommissioned later in 2025.

Type	Obsolete Endpoints:	Update to:
Endpoint	`https://api.bsn.cloud/2022/06/REST/Token`	`https://auth.bsn.cloud/realms/bsncloud/protocol/openid-connect/token`
API	`https://api.bsn.cloud/2019/03/REST/...`	`https://api.bsn.cloud/2022/06/REST/...`
API	`https://api.bsn.cloud/2020/07/REST/...`	`https://api.bsn.cloud/2022/06/REST/...`
API	`https://api.bsn.cloud/2020/10/REST/...`	`https://api.bsn.cloud/2022/06/REST/...`
API	`https://provision.bsn.cloud/rest-device/v1`	`https://provision.bsn.cloud/rest-device/v2`
API	`https://provision.bsn.cloud/rest-setup/v1`	`https://provision.bsn.cloud/rest-setup/v3`
API	`https://provision.brightsignnetwork.com`	`https://provision.bsn.cloud`

Note the existing upload API endpoint https://api.bsn.cloud/Upload/2019/03/REST/ remains unchanged and will continue to work.

API Workflow Changes

The remainder of this document will describe the steps required to obtain a new Client ID and Secret, and the changes required to the existing API workflows, along with code examples

Create Client Credentials

To create new client credentials:

Login into the new BSN.Cloud Admin Panel at https://adminpanel.bsn.cloud.

Go to Settings / Applications and select Add Application.

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 API documentation: User Guides

Click the Save button. The new Client ID and Secret will be displayed.

Copy these values and store them securely, ideally in a password manager. They will not be shown again after leaving this screen.

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 new token endpoint:
https://auth.bsn.cloud/realms/bsncloud/protocol/openid-connect/token

DO NOT USE the legacy token endpoint (https://api.bsn.cloud/2022/06/REST/Token) as this is being deprecated.

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`	OK
`401`	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`	OK - No Content
`400`	Bad Request - Network does not exist
`401`	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`	OK
`401`	Unauthorized - Access token has expired
`403`	Forbidden - Access token is not permitted to make the request

Rotating Client Secrets

If a secret is suspected to be compromised, we provide the ability to rotate it by using the Rotate Secret option. Secrets should be rotated regularly for additional security.

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.

FAQ

I use BSN.Cloud via BA:connected only. Do I need to do anything?
No, these changes only affect BSN.Cloud users that access APIs directly with code or scripts.
I use BSN.Cloud via the APIs using scripts only, do I have to do this?
Yes, you must make the changes described above. If you do not, your scripts will cease to function.
I use BSN.Cloud via the APIs using code, do I have to do this?
Yes, you must make the changes described above. If you do not, your code will cease to function.
What is the deadline for this?
When will the legacy APIs and token endpoints be decommissioned?
The APIs and token endpoints will be decommissioned later in 2025. We will be proactively monitoring the usage of the endpoints to determine the appropriate time to do this.
How will the decommissioning date be communicated?
We will contact all our customers via email and their account managers where applicable. There will be several communications up until the decommissioning date.
How do I obtain a new Client ID and Secret?
You will need to use the new BrightSign Admin Panel to create a new Application to obtain a new Client ID and Secret.
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 API documentation: User Guides
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 are no longer supported with the OAuth2 “Client Credentials Flow”.
Can I still use the old legacy API token endpoint with a new Client ID and Secret?
You should NOT do this, although it will work. The legacy API token endpoint will cease to work later in 2025.
What if I suspect my Client Secret has been compromised?
You should use the new 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.

Further Information

For further information contact: support@brightsign.biz

Documentation

BSN.Cloud Breaking Changes Guide

Introduction

BrightAuthor:connected Version Compatibility

BSN.Cloud API Deprecations

API Workflow Changes

Create Client Credentials

Get Access Token

Set Network

Use the API

Rotating Client Secrets

FAQ

Further Information

Related content