Main REST HTTP API version 2022/06

If you already have your network information, you can enter the network name/email address information for the username (for example, Test/anon@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@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: If this parameter 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 application at https://api.bsn.cloud/Upload/2019/03/REST/OAS/

See examples/uploadContentToBsn.ts in the github.com/brightsign/bsn-cloud-core repository for a sample script that uses the upload endpoint.