Main REST HTTP API version 2020/10

Owned by BrightSign TechDocs
Last updated: Feb 22, 2024
9 min read

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), 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 and user 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: The type of grant being presented in exchange for the access token. This value must be set to "password".

  • client_id 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: 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: Set this to your email address (when authenticating as a person).

  • password 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: The type of grant being presented in exchange for the access token. This value must be set to "refresh_token".

  • client_id 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: 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: 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: The type of grant being presented in exchange for the access token. This value must be set to "password".

  • client_id 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: 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: 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: The password associated with the username

  • scope 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 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: The type of grant being presented in exchange for the access token. This value must be set to "refresh_token".

  • client_id 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: 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: The refresh token issued to a user as the result of a previous authentication workflow

  • username 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 (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://api.bsn.cloud/Upload/2019/03/REST/OAS/.