SearchCtrl K



Creating private videos

September 7, 2020 - Doug Sillars in Private Videos

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. If you're interested in seeing the API reference documentation for this project, go here: Delegated upload.

Private videos

How can we keep our videos private? 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:


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.

Private videos sequence diagram

Once you capture this header, you have 2 options with subsequent requests for the private video:

  1. Add the the header on subsequent requests to authenticate the private video.
  2. Append the value of the header in the URL parameter avh for all additional requests ?avh=<token value>.


Private videos allow you to control who is able to view the video through the use of unique tokens. If the user has a valid token and X-Token-Session header in the request or url parameter, 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.

If you have any questions or suggestions, please share them on our community forum. If you are ready to start building with api.video now, create your account here. Thank you for reading!

Doug Sillars

Head of Developer Relations

Create your free account

Start building with video now