api.video

Use Cases

Tutorials

Creating Private Videos

September 7, 2020 - Doug

When it comes to publishing videos online, there are many ways that your content might be shared. There are videos that you want to share with the whole world. For other videos you might want to restrict the audience to just a handful of people, or maybe even just one person. api.video's private video solution can help you restrict who can watch the videos you have on the web.

By default, when you upload a video with api.video, the video is public, meaning that anyone with the link to the video can watch it, like the video below:

However, for videos that need to be restricted, you can use private videos to deliver the content securely to specific users. Let's learn how.

Private Videos

How can we keep our videos private and not-sharable? When creating a video with api.video, you can set the “public” attribute to false. The video is published exactly the same way, but a unique token is added to the url:

https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?token=4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85

This token is valid exactly once - so the video cannot be shared with others. When this url is accessed, the first response from cdn.api.video will contain a new header X-Token-Session, that will be used to validate every subsequent request at cdn.api.video. As long as the session header/tokens match, the viewer is authorised to watch the video and the video will play. If there is not a match, video playback will fail.

Generating the URL token

To generate the url token, you must authenticate yourself with api.video. Next,make a request for the video:

curl -X GET https://ws.api.video/videos/{videoId} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {access_token}'

The response JSON will contain urls for your video with unique tokens.

Here is a snip of the JSON response:

   "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?token=4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?token=4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85",
        "hls": "https://cdn.api.video/vod/vitkytkieTnEvUjKE0VQpd2/token/4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85/hls/manifest.m3u8",
        "thumbnail": "https://cdn.api.video/vod/vitkytkieTnEvUjKE0VQpd2/token/4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85/thumbnail.jpg",
        "mp4": "https://cdn.api.video/vod/vitkytkieTnEvUjKE0VQpd2/token/4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85/mp4/1080/source.mp4"
    }

Every time you request the video, you will generate a new token that can be used exactly once.

Private videos in practice

Once you generate a unique url with a private token, your application can request the video for playback. The next step will vary slightly depending on the video player used:

(Recommended) Using the api.video player

If you use the api.video player (using the iframe or player assets in the JSON response), the X-Token-Session header/session control is done automatically for you, and there is no further development required. This is our recommended implementation.

Using a different video player

If you are using a different video player to display your video, you will need to capture the X-Token-Session value from the initial cdn.api.video response, and submit this header/value combination in every subsequent request to cdn.api.video. To learn more about inserting custom headers, read this tutorial.

If the header is not sent on subsequent requests, the private video authentication will fail, and the video will not play for your customer.

Conclusion

Private videos allow you to control who is able to view the video through the use of unique tokens. If the user has the valid token and X-Token-Session header in the request, the user is able to see the video. If any of the authetication steps fail, playback is not authorised, and no video will play to the end user.

Doug

Doug

Developer Evangelist

Get started now

Connect your users with videos