Version 2.0 B-Deploy API Endpoints

Owned by BrightSign TechDocs
Last updated: Jun 13, 2023
8 min read

 

These endpoints allow users to automatically provision BrightSign players over the internet.

Base URL for these endpoints:  https://provision.bsn.cloud/rest-setup/v2

GET /setup/

Retrieves a device setup from the B-Deploy server.

URL Parameters

  • username string: The username associated with the device setups you wish to retrieve.

  • _id string: The unique identifier of the device setup to retrieve. If this parameter is not included in the URL, the GET request will return all device setups associated with the username.

___________________________________________________

Response

Success Response Body

200: Contains a single device setup object if the _id is specified in the URL; otherwise, this property contains the following:

  • total int: The total number of device setup objects that belong to the B-Deploy account

    • matched int: The number of device setup objects contained in the response

    • deviceSetups deviceSetup[ ]: An array of device setup objects. Each device setup object can contain the following properties:

      • _id string: A system-supplied ID for the device setup object

      • createdAt string: A UTC timestamp indicating when the device setup object was created. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ

      • updatedAt string: A UTC timestamp indicating when the device setup object was last modified. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ

      • bDeploy bDeploy{ }: A B-Deploy object containing the following properties:

        • username string: The BSN.cloud username

        • networkName string: The BSN.cloud network name

        • packageName string: The client-defined name for the device setup package. This value must be unique among device setup packages that belong to your person entity.

      • bsnDeviceRegistrationTokenEntity tokenEntity{ }: A TokenEntity object containing the following properties:

        • token string: The device registration token

        • scope string: The scope of the device registration token

        • validFrom string: The beginning of the token validity window  

        • validTo string: The end of the token validity window  

      • bsnGroupName string: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.

      • setupType string: The device setup type. This value is currently always "bsn".

      • version string: The B-Deploy cloud version. This value should currently be "2.0.0"

      • deviceName string: The name given to devices that are provisioned with the device setup package

      • deviceDescription string: The description give to devices that are provisioned with the device setup package

      • url string: An optional value of the Partner Application URL specified for a device to use when finding the application to download.

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method.

5XX: Any 500 code is an internal server error

POST  /setup/

Adds a new device setup to the B-Deploy server.

Request Body

The following list includes only required properties for device-setup creation.

  • version string: The B-Deploy Cloud version. This value should currently be "2.0.0".

  • setupType string: The device-setup type: "bsn", "lfn", "sfn", "standalone", or “partnerApplication”

  • bsnGroupName string: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.

  • url string: An optional value of the Partner Application URL specified for a device to use when finding the application to download.

  • remoteDwsEnabled bool: A flag indicating whether the Remote DWS is enabled or disabled on the player

  • bDeploy bDeploy{ }: A B-Deploy object containing the following properties: 

    • username string: The BSN.cloud username

    • networkName string: The BSN.cloud network name

    • packageName string: The client-defined name for the device setup package. This value must be unique among device setup packages that belong to your person entity.

    • client string: An optional name of the client creating the device setup package. This value can be arbitrary and is not related to the BSN.cloud client identifier or client secret tokens.

    • url string: An optional url to a custom application URL. This value will be ignored if setupType is NOT set to “partnerApplication”.

  • bsnDeviceRegistrationTokenEntity tokenEntity{ }: A registration token that is used to register the device with a BSN.cloud network. Here is a request example:

curl --location --request POST 'https://api.bsn.cloud/2020/10/REST/provisioning/setups/tokens/' \ --header 'Accept: application/json' \ --header 'Accept-Encoding: gzip,deflate' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer 5BfFL3npQscN4RQUeO3V1EI8QKQzToBoVFkLAGg3qmcvsDSgFIt1OIc2P' \ --data-urlencode 'grant_type=user_access_token' \ --data-urlencode 'user_access_token=<redacted>' \ --data-urlencode 'client_id=<redacted>' \ --data-urlencode 'client_secret=<redacted>'

The expected response to that request would include the following information: 

  • token string:  A device registration token. The server returns this token, which allows devices to provision themselves for a BSN.cloud network. Note that this is not a user token.

  • scope string: The scope of the device registration token 

  • validFrom  string: The start of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

  • validTo string: The end of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

See this page for information about how to get a user access token.

___________________________________________________

Response

Success Response

200: The unique identifier of the device setup object

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

PUT  /setup/

Updates an existing device setup on the B-Deploy server. You must include the _id property in the device setup object to specify the device setup to update.

Request Body

  • _id string: The unique identifier of the device setup object to modify

  • version string: The B-Deploy Cloud version. This value should currently be "2.0.0".

  • setupType string: The Device Setup type. This value is currently always "bsn".

  • bsnGroupName string: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.

  • url string: An optional value of the Partner Application URL specified for a device to use when finding the application to download.

  • remoteDwsEnabled bool: A flag indicating whether the Remote DWS is enabled or disabled on the player

  • bDeploy bDeploy{ }: A B-Deploy object containing the following properties:

    • username string: The BSN.cloud username

    • networkName string: The BSN.cloud network name

    • packageName string: The client-defined name for the device setup package.

    • client string: An optional name of the client creating the device setup package. This value can be arbitrary and is not related to the BSN.cloud client identifier or client secret tokens.

  • bsnDeviceRegistrationTokenEntity tokenEntity{ }: A TokenEntity object that is used to register the device with a BSN.cloud network. 

    • token string:  A device-registration token. The server returns this token, which allows devices to provision themselves for a BSN.cloud network. Note that this is not a user token.

    • scope string: The scope of the device registration token

    • validFrom string: The start of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

    • validTo string: The end of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

___________________________________________________

Response

Success Response

200: The existing device setup has been updated

Failure

400: Either the request or request body is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

DELETE  /setup/

Deletes a device setup from the B-Deploy server.

URL Parameters

  • _id string: The unique identifier of the device setup to delete

___________________________________________________

Response

Success Response

200: The specified device setup has been removed

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

5XX: Any 500 code is an internal server error

GET  /device/ 

Retrieves a device object associated with the B-Deploy account.

URL Parameters

  • _id string: The unique identifier of the device object to retrieve. If this parameter is not included in the URL, the GET request will return all device objects associated with the account

___________________________________________________

Response

Success Response Body

Contains a single device object if the _id is specified in the URL; otherwise, this property contains the following:

  • total int: The total number of device objects that belong to the B-Deploy account

    • matched int: The number of device objects contained in the response

    • Players device[ ]: An array of device objects. Each device object can contain the following properties:

      • _id string: The unique identifier of the device object 

      • setupId string: The _id of the device setup object associated with the device object. The player will use the associated device setup to provision itself.

      • serial string: The serial number of the player represented by the device object

      • createdAt string: A UTC timestamp indicating when the device setup object was created. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ

      • updatedAt string: A UTC timestamp indicating when the device setup object was last modified. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ

      • url string: An optional value of the Partner Application URL specified for a device to use when finding the application to download.

      • client string

      • __v string

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method.

5XX: Any 500 code is an internal server error

POST  /device/

Adds a device object to the B-Deploy account.

Request Body

  • serial string: The serial number of the player represented by the device object

  • setupName string: The name of the setup file

  • NetworkName string: The name of the network

  • url string: The URL from which the player will download its presentation as part of the final provisioning step

  • setupId string: The _id of the device setup object associated with the device object. The player will use the associated device setup to provision itself.

___________________________________________________

Response

Success Response

201: The unique identifier of the device object

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

PUT  /device/

Modifies a device object associated with the B-Deploy account.

Request Body

  • serial string: The serial number of the player represented by the device object

  • url string: The URL from which the player will download its presentation as part of the final provisioning step

  • setupId string: The _id of the device setup object associated with the device object. The player will use the associated device setup to provision itself.

___________________________________________________

Response

Success Response

200: The existing device setup has been updated

Failure

400: Either the request or request body is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

415: The server cannot accept the data representation that you sent (as specified in the header)

5XX: Any 500 code is an internal server error

DELETE  /device/

Removes a device object from the B-Deploy account.

URL Parameters

  • _id string: The unique identifier of the device object to delete

___________________________________________________

Response

Success Response

200: The specified device object has been removed

Failure

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

5XX: Any 500 code is an internal server error