Authentication (REST)

Broadsign's REST architecture supports two authentication methods: an HTTP token and certification/public key fingerprint.

We recommend that you use these methods in the following ways:

  • HTTP Token: The HTTP token is easy to generate and use. We recommend that you use it to authenticate calls made to your sandbox domain. See About the Sandbox (REST).
  • Certification/Public Key Fingerprint: Due to its high level of security, we recommend that you use certification to authenticate calls made to your production domain.

Note: The use of each authentication method requires some work in Broadsign Control Administrator. You will need a registered user on an active domain.

Note: Your sandbox and production domains are separate entities. You will need a separate Broadsign Control API user for each domain, each with its own unique ID#. Also, you will need to authenticate calls on each domain separately (that is, separate tokens or public key fingerprints on each).

You can generate and use an HTTP token for secure access to Broadsign’s REST architecture. A user with the necessary privileges generates the token in Broadsign Control Administrator. That user then passes the credentials in the headers of their REST requests.

You must call REST over HTTPS. Calls made over HTTP or without authentication will fail.

To request that a user be granted REST access, contact Broadsign Services and provide the user ID#.

Note: When you generate the HTTP token you must copy it to your clipboard. Once you close the dialogue box, you will be unable to see the token again. To see it, you must generate a new one. Once copied to your clipboard, we recommend pasting it into a text editor right away.

To generate the HTTP token:

  1. Select the user on your domain that will call use REST.
  2. To enable access, contact Broadsign Services. Provide them with your domain and the API user ID#. Broadsign Services will confirm API access for that user ID#.

  3. In Broadsign Control Administrator, open the User Properties (see Edit User Properties). Go to the Credentials tab.

  4. To obtain a token, under REST API Authorization Token, click Generate Token. The REST API Token dialogue box opens.

    Note: When you generate the HTTP token you must copy it to your clipboard. Once you close the dialogue box, you will be unable to see the token again. To see it, you must generate a new one. Once copied to your clipboard, we recommend pasting it into a text editor right away.

  5. Click OK, and then click Apply.

Here is a sample request with the HTTP token:

Copy 
curl  -X GET "https://api-sandbox.broadsign.com:10889/rest/criteria/v8/12345" -H "accept: application/json" -H "Authorization: Bearer YourAPIKeyHere"

Note: This sample includes the endpoint for a sandbox domain. The production endpoint is different: https://api.broadsign.com

When integrating with Broadsign Control API in production, we recommend a cryptographic certificate and key.

You must install them on the client machine that is associated with a user — with proper privileges — in Broadsign Control Administrator. For auditing and security reasons, it is best to create a new user solely for use with Broadsign Control API. Simply add a new user through Broadsign Control Administrator, choose an arbitrary password and assign the proper privileges.

Then, you must generate a private key and submit a Certificate Signing Request (CSR) to Broadsign. Broadsign will respond with a signed certificate and a public key fingerprint:

  • The signed certificate and your private key are your authentication tokens.
  • The public key fingerprint is assigned to the user you created, thereby allowing Broadsign Server to authenticate the user and assign the correct security context.

To authenticate your Broadsign Control API user:

  1. Create the private key:

    Copy 
    openssl genrsa -out sdk_key.pem 2048

  2. Create the Broadsign Certificate Signing Request (CSR):

    Copy 
    openssl req -new -key sdk_key.pem -out sdk_req.pem
    • Fill out the fields accurately.
    • DO NOT specify any of the following extra attributes:
      • a challenge password
      • an optional company name

  3. Send the Certificate Signing Request (CSR) to Broadsign. Include the following information:

    • To: services@broadsign.com
    • Subject: SDK CSR
    • Attachment: [sdk_req.pem]

    • Body: Please find attached the API Certificate Signing Request for [your company's name].

      Warning: Do not send your private key. Keep it secure at all times. Anyone with access to your private key could make unapproved changes to your domain.

      Note: If the email address from which you send the request is unregistered at Broadsign Community, you will receive a bounce-back email. You will need to have a registered contact from your organization contact us to register the email.

  4. Receive the signed certificate and the public key fingerprint from Broadsign.
  5. Assign the public key fingerprint to your designated Broadsign Control API user:
    1. In Broadsign Control Administrator, from the resource tabs on the left, select Users.
    2. Find and double-click your Broadsign Control API user.
    3. In the User Properties, go to the Credentials tab.

    4. In the Public Key Fingerprint section, paste your fingerprint.

      • The user making the requests must have a valid fingerprint value that matches the certificate being used on the client side of the mutually-authenticated SSL connection.
      • The fingerprint is a series of hexadecimal characters, 20 pairs separated by colons.

The local certificate allows Broadsign Server to authenticate you.

When sending requests to Broadsign Control API, the request needs a merged key and certificate file. Concatenate both your private key and the signed certificate provided by Broadsign Services.

To create your local certificate:

  1. Put the sdk_key.pem and sdk_cert.pem files into the same folder.
  2. Using the terminal, browse to the directory.

  3. Execute the command below:

    Copy 
    cat sdk_key.pem sdk_cert.pem > merged_cert.pem

For Windows users:

  1. Using your text editor, create a new file named merged_cert.pem.
  2. Append the content of sdk_key.pem and sdk_cert.pem, in that order.

The final file should resemble the image below.

Note: This is a false certificate. Do not copy.

Do not confuse scoping as we use the term in Broadsign Control Administrator, with scoping as we use the term in Broadsign Control API.

  • In Broadsign Control Administrator, "scoping" refers to restricting what users can view, as described in the Scoping feature.
  • In Broadsign Control API, "scoping" refers to narrowing the results of specific list operations.

    • Note: It is not possible to limit the resources accessible to an API user on a specific endpoint if the user has the necessary access privileges for it.