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.

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 API documentation: https://docs.brightsign.biz/space/DOC/1230241793

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.

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

Code	Description
`200`	OK
`401`	Unauthorized - Invalid Credentials

Notable Response Data

Property	Description

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

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

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

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: https://docs.brightsign.biz/space/DOC/1230241793
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.

Further Information

For further information contact: support@brightsign.biz

Documentation

BSN.Cloud 2025 API Usage Guide

API Workflow

Create Client Credentials

Get Access Token

Set Network

Use the API

Rotating Client Secrets

FAQ

Further Information

Related content