Protecting videos and streams

Normal access of content in TwentyThree

In TwentyThree, every video or stream has an ID (photo_id or live_id) and a matching token (token) that can be used to look up information about the item in the API -- and ultimately also play the video in a player. This information is used with the embed code, with the API and in many case also on the video website.

The rules for accessing videos and streams in TwentyThree are simple:

Protected content

The only exception to these rules is when a video or a stream is "protected": In those cases, you can still embed content and find its meta data using the API -- but to actually play the video or stream, the user needs to be authenticated further.

The cases for using this are many, but a few examples include:

A number of these features are included out-of-the-box in TwentyThree, but we also offer the ability to have the player query a custom endpoint or web address to gain access to any video or stream.

Behind the scenes, this feature works by:

Custom endpoints

TwentyThree supports verification through custom off-site endpoint, which can be useful if you want to verify, for example, that a users is logged in and has paid for a subscription -- or indeed that the person meets any kind of custom criteria needed by your workflow.

Specifically in these cases, the player sends a JSON-P formed request with a callback parameter to the endpoint. For example:

http://my.server.com/verify?callback=somefunction&protection_method=password&object_type=photo&object_id=3079141

In return it expects a JSON response wrapped in a function for cross-domain communication. The response must include the correct protected_token for the object:

somefunction({
  "status": "ok", 
  "protectedtoken":{"object_id": "3079141", "object_type": "photo", "protected_token": "abcedf12345689"}
});

The correct protected_token is available through an OAuth-signed call to /api/photo/list with read permissions or higher. It is also returned from when an item is protected through the API. In either case and for performance reasons, it's important that this information is pre-fetched and cached for delivery.

If the user does not have access to the ressource, return an error in the same JSON-P format while honouring the callback parameter:

somefunction({
  "status": "error", 
  "message":"The password is not correct."
})

Cycling tokens in protection

Protection tokens in TwentyThree are static strings by default. This means that they won't change over time, unless they are configured to do so. This makes implementation easy, but in certain security designs you may want to update the protection token on an ongoing basis. This can be done in two different ways:

1. Using the API to change tokens: Calling /api/protection/protect on an object will change the protection token. If you want to leave some room for clients playing from the old protection token, you can include allow the old token to live on using the grace_minutes parameter.

2. Using automatic token cycling: Any account on TwentyThree can be configured to automatically cycle token at specified intervals. In this scheme, you can contact TwentyThree support to set up cycling; and you will be able to receive automatic notifications of token changes through the Webhooks API (using the photo_protect, photo_unprotect, live_protect and live_unprotect events). Again, a grace period for old tokens can be used with this scheme.

Protection with People

TwentyThree allow realtime tracking of viewer profiles. To use this feature alongside the Protection API, simply include visitor information in the callback function:

somefunction({
  "status": "ok", 
  "protectedtoken":{
      "object_id": "3079141", 
      "object_type": "photo", 
      "protected_token": "abcedf12345689",
      "profile": {
         "email":"howard.james@ranguinc.com",
         "firstname":"Howard",
         "lastname":"James",
         "company":"Rangu Inc",
         "phone":"+45 12 34 45 56",
         "title":"Video Producer"
      }
  }
});