Resource URI

A Resource URI is a pointer to a broadcast.

Here's what they look like:

https://cdn.bambuser.net/broadcasts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Purpose

All broadcasts are private by default. Resource URIs can be used to grant privileged actors access to broadcasts. This can either be a specific broadcast or any broadcast matching certain criteria (see Virtual Resource URIs).

To make a broadcast watchable, broadcast owners should use their signing keys to generate a signed Resource URI and distribute it to their audience.

The Bambuser player SDKs for Android and iOS, as well as the web player, require a signed Resource URI as input. See Playback for how to use Resource URIs in your players.

As a Bambuser customer, your backend, which is aware of your auth scheme, should decide whether and when a given viewer should be allowed to view a specific broadcast and hand it a signed Resource URI.

You can either make your backend capable of signing Resource URIs with your signing keys, or use the pre-signed Resource URI generated automatically for each broadcast.

Using pre-signed resource URIs

If you don't need custom authorization and simply want to let anybody access a broadcast, the API provides pre-signed Resource URIs which can be used more than once and do not expire.

Pre-signed Resource URIs are also included in Webhooks.

Similarly, the API for image metadata provides image URLs which don't have any access restrictions.

Creating a signed Resource URI

The access control behaviour for a Resource URI can be modified by certain parameters defined by a specific protocol described below.

A Resource URI signed by your backend is by default valid for a single view attempt which must begin within one hour. If desired, this behavior can be modified by including da_ttl and da_static as signature parameters. The default behavior is well suited for private limited sharing, intranets, serving content behind paywalls etc.

Requirements

1) A broadcast's id

You can discover the id:s for your broadcasts through any of the following sources:

2) Signing keys

A set of signing keys consists of a da_id and a da_secret_key.

You'll find yours on: dashboard.bambuser.com/developer.

Creating a signature

1) Start by constructing a Resource URI

Append the broadcastId to the CDN:s base URL:

https://cdn.bambuser.net/broadcasts/broadcastId

2) Append signing parameters

Select appropriate values for each of the signing parameters and add them as query parameters to the Resource URI created in the previous step (line breaks added for readability):

https://cdn.bambuser.net/broadcasts/broadcastId
  ?da_id=YOUR_DA_ID
  &da_timestamp=1471360487
  &da_nonce=0.7911932193674147
  &da_signature_method=HMAC-SHA256

3) Generate a signature

Add GET at the start of the result of the previous step. Then produce a hex digest of the HMAC (SHA-265) of the string using your da_secret_key as the secret key. The result of this operation is your signature.

4) Append the signature

Finally, add the signature to the end of the Resource URI as a query parameter named da_signature (line breaks added for readability):

https://cdn.bambuser.net/broadcasts/broadcastId
  ?da_id=YOUR_DA_ID
  &da_timestamp=1471360487
  &da_nonce=0.7911932193674147
  &da_signature_method=HMAC-SHA256
  &da_signature=signature

5) That's it!

You now have a signed Resource URI.

Example code

Signing parameters

name type description
da_id string Your public signature id which corresponds to your secret key. You'll find yours on: dashboard.bambuser.com/developer
da_timestamp integer Timestamp, given as seconds since January 1 1970 (UTC). Used as a security measure, to invalidate the signature a reasonable number of minutes after the request is signed.
da_nonce string A random value chosen by you. Choose a different nonce value for each request. For signed requests with unique nonce values, the Bambuser backend will block attempts to replay the request after being used once.
da_signature_method string Indicates which algorithm was used to generate the signature. Use the value HMAC-SHA256.
da_ttl integer Duration, given as seconds, defining how long the signed URI is valid, counting from da_timestamp. The default value is 3600 seconds. TTLs of less than a few minutes is generally not recommended due to potential synchronization issues between server clocks.
da_static boolean When set, this parameter makes the signed URI valid for repeated use, effectively making the Bambuser backend ignore any da_nonce.

Virtual Resource URIs

Virtual Resource URIs lets you target broadcasts by certain criteria instead of addressing one specific broadcast by its id.

These can be used in situations where you want to play any currently live broadcast or the last broadcast by author X.

Virtual Resource URIs can be generated using a tool found on the Developer page.