API client

Private Videos

Normal

small_t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

thumbnail_t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

Artem Matinian

Product updates

NodeJS

The internet is fascinating; vast information zooms through back and forth, enabling millions of people worldwide to share their knowledge and experiences. However, it’s also a place where one must be cautious and protect oneself regarding private content and limit access to personal information, especially videos. We understand that it’s a sensitive topic for many it's difficult to implement on your own, so we created Private Videos.

## Secure & manage access to your videos

Maybe you are asking yourself: “ok, but how does *video privacy setting* help me?”. There are quite a few use cases for private videos, and we’ve discussed the hassle of securing the videos yourself. 

- On-demand videos behind a paywall
- Content Protection
- Video NFTs
- Video for internal use only
- Private video messaging
- Disposable one-time videos

And pretty much any video where you want to limit or restrict access! 🔒

### What are private videos

A private video is a video object secured by a private token and can be consumed only once. After the private token is consumed, the video is only available once you have another private token assigned to it. So, even if your user has the video URL, sharing it with anyone else is useless. 

We tried to make it as simple as possible to secure your videos:

- Create a video container with a `public: false` flag, which will make the video (surprise 🥳) private!
- Private videos will generate a new private token each time a request is made for that video id.
- Each private token is usable only once.

If you like to get into nitty gritty details, feel free to check out our docs about [Private Videos](https://docs.api.video/docs/private-videos).

### How to deliver private videos to your audience

After you learn how private video works and what it’s good for, we can now talk about the delivery part, which is the most important part. 

To reiterate the private video concept, here’s a visual representation of how the whole thing works:

large_private-videos-1.png

medium_private-videos-1.png

small_private-videos-1.png

thumbnail_private-videos-1.png

private-videos-1.png

Knowing that now we can finally start building stuff! 

It’s that simple! (if you want the advanced stuff, scroll down to “Time to roll up our sleeves!”)

Let’s try to deliver one video in HTML with our own (amazing!) [api.video](http://api.video) player. 

Suppose you already have a cool video uploaded. Go to the dashboard and get make the video private (if it’s not already private)

Now that the video is private, we can deliver it to users. Here’s a quick snippet in HTML that you can use to play your video in the browser. Just copy the code snippet and replace the URL with your private video URL. You can find the video URLs in the Assets section of the Video Details:

large_screenshot-2023-02-09-at-20-41-37.png

medium_screenshot-2023-02-09-at-20-41-37.png

small_screenshot-2023-02-09-at-20-41-37.png

thumbnail_screenshot-2023-02-09-at-20-41-37.png

screenshot-2023-02-09-at-20-41-37.png

We played the video once with a browser. Now, open another browser tab in incognito mode and play the same video. You can see that it’s gone! no more video! don’t worry; even though the video still exists, the token changes once you consume it. If you refresh the video details page, you’ll notice that the private token has changed. If you paste the URL with the new private token in the `src` you will be able to play the video again in a new tab, but already with a different private token. Cool right? 🙂

### Let’s get programmable

The concept works the same for API requests. You can request the API and fetch the video by id; if it’s a private video the response will give you the URLs with the private tokens (the `XYZ` in the URLs stands for the private token):

test video

### Assets? what assets? 🏠

Notice that JSON above has a field called `assets`. We’ll refer to assets later, but it’s important to know what they are. Assets include the URLs for the video thumbnail, iframe with the [api.video](http://api.video) player for embedding directly into the HTML, and several other video formats like `mp4` and `hls`. Now you know! 💡

### How to create a sample app with private videos

Now that we know the privacy setting concepts, it’s time to write some example apps that will give us a small glimpse into what powerful tool we are dealing with here.  

Let’s assume that we want to build an app that will display all the private video thumbnails on our website and make them clickable so it will open a video once it’s clicked. Something like that:

On the backend, we will have to do some magic. While with public videos it’s pretty simple as just returning the videos, for private videos we will need to get the session first. Let’s look at the HTML code:

large_screenshot-2023-02-10-at-19-43-18.png

medium_screenshot-2023-02-10-at-19-43-18.png

small_screenshot-2023-02-10-at-19-43-18.png

thumbnail_screenshot-2023-02-10-at-19-43-18.png

screenshot-2023-02-10-at-19-43-18.png

Notice the `avh` parameter in the query string? The `avh` parameter is where you will pass the session token... oh wait, what's a session token?!

### Session token & session management

Session Tokens are designed to retain the same session for a user. Let’s take an example - a user opened a tab with the private video and would like to refresh the tab, or the video didn’t work with our player for whatever reason. Hence, you redirect the user to an mp4 version of that video (different asset). For these cases, we’ve created the session tokens.

There are two types of tokens for private videos:

- **Private token** (which we already discussed): generated every time you pull a private video from the API.
- **Session token**: This token is used to retain the private video session with the same private token.

At a very high level, to request different assets for the same private video, more than having the private token is required; you also need to retain the session. For that, we have the session token. In the flowchart below, you can see that for each private video, we are using a session token + the private token:

large_private-videos-post-15feb23.png

medium_private-videos-post-15feb23.png

small_private-videos-post-15feb23.png

thumbnail_private-videos-post-15feb23.png

private-videos-post-15feb23.png

So let’s get a bit technical here. To start the session, you will need to request the `/session` endpoint, get the session token, add it to the first asset you request, and then add it to every following asset you request. In the example above, we will request the `/session` endpoint, then add the session token to the query string of the private video thumbnail → request an embedded video asset with the session token in the query string → request a private video asset in mp4 format with the session token, and so on, you got the idea 😄

In other words:

Get the session token:
`GET https://vod.api.video/vod/{videoId}/token/{private token}/session`

Response:
`{"session_token": "111-222-333"}`

Now we can request the private video thumbnail asset → embedded video → mp4:

`GET https://vod.api.video/vod/{video id}/token/{private token}/thumbnail.jpg?avh={session token}`

`GET https://embed.api.video/vod/{video id}?token={private token}&avh={session token}`

`GET https://vod.api.video/vod/{video id}/token/{private token}/mp4/source.mp4?avh={session token}`

Sample runnable code of the above app in Node.js:

Let’s do a step-by-step review of what we are doing here.

1. We are creating a server that will serve HTML on port 3000 with Node.js
2. To make it easy on ourselves, we create a wrapper that will make an HTTP request to [api.video](http://api.video) with api key already embedded in HTTP header. That’s the `apiVideoReq` function.
3. We will get a raw response from the apiVideoReq, so need to create a parser that will parse the JSON response if the request is successful (200). That’s going to be the `getJsonResponse` 
4. Then we need to create a function that will get the list of our videos. That’s pretty simple with the wrapper function we have, so let’s reuse the `apiVideoReq` and make a request to `[https://ws.api.video/videos](https://ws.api.video/videos)` endpoint. You can find more info about the `/videos` endpoint [here](https://docs.api.video/reference/list-videos).
The response we'll get is an array of objects of the following format:

Notice that the second object has a property `public` which is set to `false` , which means that the video is private; hence we need to get all of these videos. 

1. Extract all the private videos from the list by creating an iterator that will run through the array of objects and get each video with the flag `public` set to `false` pushing only the assets and video id into a new array.
2. If you remember, we need to get the session token by requesting the /session endpoint. The endpoint accepts the video id and private token; however, if you notice the private token is only in the URL. So let’s extract it! we can use this simple regex to extract it from the embedded URL `(?<=token=).*$` 
3. We first extract the private token from the URL and map it to the asset objects (with the video URL, video id, etc.) 
4. Then we request the /session endpoint passing in the video id and private token, and we get the session_token. Now we can also map to the same asset object.
5. We’re almost done; hang in there! now let’s get generate `<img>` tags with the src as the asset thumbnails and add the session token in the query string as an `avh` parameter, i.e: `<img src=https://vod.api.video/vod/AABBCC/token/c77d7bf3-4e2f-4a85-9e15-5c35992c11fc/thumbnail.jpg?avh={{session token}}>` .  Then in the same line generate the <a href> tag that will lead us to the actual video, and as you understood already, it too has to include the session token, i.e: `<a href=https://embed.api.video/vod/AABBCC?token=c77d7bf3-4e2f-4a85-9e15-5c35992c11fc&avh={{session token}}>`
6. And lastly, generate the HTML `<head>` and `<body>` while encapsulating the `<a href><img></a>` we’ve already created, and…. DONE!

Now you have clickable thumbnails of your private videos which you can secure behind user credentials for example 🙂

Let’s summarize what we’ve learned here:

- We’ve understood how private videos work and the purpose of private videos with real-life use cases.
- We’ve also built a small app to leverage private videos to create clickable thumbnails with minimal code.

If you have any questions or feedback about this article, do not hesitate to contact our support. You can also find the docs for private videos [here](https://docs.api.video/docs/private-videos).

large_14feb23-copie-2.png

medium_14feb23-copie-2.png

small_14feb23-copie-2.png

thumbnail_14feb23-copie-2.png

14feb23-copie-2.png

Video Access Management: How to create, deliver, and manage private videos and what are they anyway?

Android

Mobile

Player

Player update

thumbnail_thibault_rond.png

thibault_rond.png

Thibault Beyou

Tutorials

Kotlin

We have now released an [api.video](https://api.video/) player for Android. The api.video player helps you to include your videos in your Android applications very easily and quickly. In this tutorial, we are going to show how to add an api.video player to your Android application. It will only take 5 minutes. Let’s do this! 👊

Before starting this tutorial, you can upload a video to your api.video. If you haven’t yet, you can check [Upload your first video guide](https://docs.api.video/docs/upload-your-first-video), which will walk you through your first video upload. The video that you have uploaded to your api.video account will have an assigned `videoId`. In the following steps, we will call for your videoId using the `YOUR_VIDEO_ID` parameter.

To just give you a quick preview, we are going to create an Android application with an api.video player that looks like this:

## The api.video player for Android

The api.video Android player is available on GitHub and comes with an example application, and the artifact is hosted on Maven Central.

The minimum Android API version supported by the api.video Android player is 24. Make sure that you don’t have a `minSdk` version under 24.

The API is divided into 2 main components:

- **The player view:** This component displays the video and its controls: `ApiVideoExoPlayerView` class.
- **The player controller:** This component controls the video and its events: `ApiVideoPlayerController` class.

## Add api.video Android player to your project

If you don’t have an Android application yet, you need to create one before you go further. The [Build Your First Android App in Java](https://developer.android.com/codelabs/build-your-first-android-app#0) is a simple guide that will help you create your Android application. 

### Dependency

The first thing is to add the [api.video](https://api.video/) Android player to your project dependencies. In your application `build.gradle`, add your `dependencies` tag as shown below:

It’s always good to check out if a [new version](https://github.com/apivideo/api.video-android-player/releases) is available.

To have access to the view, I am going to use `ViewBinding` in this tutorial because it is elegant to use as it will be more user-friendly. Now we add the `android` tag:

### XML Layout

In your `Activity` layout, add a player view:

You might have some constraints to add depending on the parent layout.

With `ViewBinding`, we can access our `ApiVideoExoPlayerView` by using the following field:

### Implementation

The main part of the implementation is to create a player controller, but it depends on several other components.

To manipulate video from api.video, the `videoId` is wrapped in an object called `VideoOptions`:

Create a player controller in your `Activity`. For example, in the `onResume`:

Launch the application. You have successfully integrated the [api.video](http://api.video) Android player in your application! 🥳🥳🥳

### Video privacy setting

For more information on changing video privacy settings, see this [article](https://api.video/blog/product-updates/video-access-management-how-to-create-deliver-and-manage-private-videos-and-what/).

If your application requires the use of private videos, then pass your private token to the `VideoOptions`:

### Fullscreen

For the fullscreen button, you will have to develop the fullscreen behavior. The base principles are: 

* When full screen is activated, hide all surrounding views, menu,…, and lock the application in landscape mode.
* When the full screen is deactivated, display surrounding views and unlock the application orientation.

These behaviors must be implemented on the `onFullScreenModeChanged` of `ApiVideoExoPlayerView.Listener`:

In this quick tutorial, you learned about how to simply add an [api.video](http://api.video) player for your Android application. Now you know how to add the api.video player as a dependency, configure the XML layout, and implement the player controller. Moreover, you learned how to change your video privacy and how to set up a fullscreen behavior. 

You can successfully integrate the api.video Android player in your own application by following the steps in this tutorial. For an example of api.video Android player, see the [example](https://github.com/apivideo/api.video-android-player/tree/main/example) provided in the player repository.

If you miss any features, face any bugs, or come across any other issues, we will be happy to help you on our [GitHub issues](https://github.com/apivideo/api.video-android-player/issues) page.🤝

large_23nov22-1.png

medium_23nov22-1.png

small_23nov22-1.png

thumbnail_23nov22-1.png

23nov22-1.png

How to add an api.video player to your Android application

Delegated Upload

video create

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Where I live in the UK, there are miles and miles of footpaths - publically accessible trails that cross private property.  There's an expectation that those that use the public footpaths will respect the land/plants/crops of the private owners, in exchange for access to the beautiful countryside.

## Public access to api.video

api.video has a concept of [delegated tokens](https://api.video/blog/tutorials/delegated-uploads) which works like a public key - granting anyone with the key access to upload videos into your account. Now, much like the public footpaths, the usage of the public key is expected to be reasonable, and not overused.

But...it is the internet. While most of the users will behave and use the delegated upload appropriately, there might be a bad egg or two that cause issues. To help mitigate public token upload abuse, we have added [revocation](https://docs.api.video/reference/delete_upload-tokens-uploadtoken) of delegated tokens. We also have added a 'time to live' where you can provide an expiration time (in seconds) to your token.

So we've wrapped some security around the major vector to delegated token abuse. Even with this change, we have not alleviated all the questions from our customers who are grappling with ideas of privacy with a public token.  In this post, we'll show how to address the most common concerns we've heard from our users. 






## Public, but Private

*"Can I have a 'one use' delegated token?*

This is a fabulous idea - it completely removes the issue of delegated token abuse - the token "self destructs" upon video upload.



thumbnail_single-use.jpeg

single-use.jpeg

*"Can I make a delegated upload private by default?"*


A [private video](https://api.video/blog/tutorials/tutorial-private-videos) has a unique token in the url that allows **one view** of the video.  Each time the video is served, a new URL must be requested from api.video. This prevents the general public from seeing the video, and allows you to decide on the access.  By default, all videos are public.

Sometimes, as we walk the footpaths, we come across a path that is marked as private - the landowner does not want the public in that area.  

Setting a public, delegated token to private videos is like the "No Trespassing sign" on the footpath.

medium_notrespassingbydjuradjvujcic.jpg

small_notrespassingbydjuradjvujcic.jpg

thumbnail_notrespassingbydjuradjvujcic.jpg

notrespassingbydjuradjvujcic.jpg



*"Can I disable mp4 download link by default?"*

By default, the ```mp4Support``` parameter is set to ```true```, allowing the download of a private video.  By setting this to false, you can prevent the download from occurring.  Another "keep out" sign on the public path, if you will.


medium_forbidden.jpg

small_forbidden.jpg

thumbnail_forbidden.jpg

forbidden.jpg

 
### Private access, but with the public token??

Can we make the video private and disable the mp4 *while* using the public delegated token?  You can!  

Can we create a single-use delegated token - one per video upload?  Yes, we can (to a degree).  But I think this approach is close enought to a unique upload token to be secure and protect your account from bad actors on the internet.


## Demo Time

We've created a demo showing a public/private upload.  You can try it out yourself at [privatelyupload.a.video](https://privatelyupload.a.video/).


When you visit this page, you see a form for video upload.  I am writing this post in mid-December, so will use a trailer from a classic Christmas movie in my upload:

online form for video upload. We'll be uploading the Die Hard trailer.

large_screenshot-2020-12-17-at-15-46-49.png

medium_screenshot-2020-12-17-at-15-46-49.png

small_screenshot-2020-12-17-at-15-46-49.png

thumbnail_screenshot-2020-12-17-at-15-46-49.png

screenshot-2020-12-17-at-15-46-49.png

When I begin the upload (by selecting the video), I create an XMLHTTPRequest to the server with the video name, description, and if the video should be public/private, support/not support mp4:

### Set video privacy

This request is sent to the "createVideo" endpoint on my server.  The Node server extracts the JSON from the body, and creates a video container at api.video.  When we create the container, we can set the privacy settings for the video to be uploaded - namely if it should support mp4 download, and if the video should be public or private.

>This solves 2 of the questions asked above - 'can a delegated upload be set to private?' and 'Can I disable mp4 support?'.

```javascript
	if(req.body.public === "false"){
		public=false;
	}
	var mp4  = true;
	if(req.body.mp4Support === "false"){
		mp4=false;
	}
	var title = req.body.title;
	var descr = req.body.description;

	client = new apiVideo.Client({ apiKey: apiVideoKey});	
	
	
	let result = client.videos.create(title, {	"title": title, "mp4Support": mp4,
		"public": public, 
		"description": descr,					
	});

```

The response from the create video has a videoId that we will use as the container for the video we are about to upload.  This container is already built with the privacy settings requested on the webpage!

### One use upload token

Next, we'll create a delegated token with a TTL of 90 seconds.  Note - the TTL support is not yet in the Node SDK (it launched last week!), so we make HTTP requests to the API endpoint.

1. [Authenticate our apiKey](https://api.video/blog/tutorials/authentication-tutorial). This will return an authentication key in a second request for the token.  2. [Create a delegated token](https://docs.api.video/reference/get_upload-tokens) with the desired TTL (set to 90s in the code).  The response will give us the delegated token, and when it expires ("expiresAt").

```
var authOptions = {
			method: 'POST',
			url: 'https://ws.api.video/auth/api-key',
			headers: {
				accept: 'application/json'
				
			},
			json: {"apiKey":apiVideoKey}

		}
		console.log(authOptions);	
		request(authOptions, function (error, response, body) {
			if (error) throw new Error(error);
			//this will give me the api key
			
			var authToken = body.access_token;
			console.log(authToken);
			//now use this to generate a delegated toke with a ttl of 90s
			var tokenTTL = 90;
			var tokenOptions = {
				method: 'POST',
				url: 'https://ws.api.video/upload-tokens',
				headers: {
					accept: 'application/json',
					authorization: 'Bearer ' +authToken
				},
				json: {"ttl":tokenTTL}
	
			}
			request(tokenOptions, function (error, response, body) {
				if (error) throw new Error(error);
				var delegatedToken = body.token;
				var tokenExpiry = body.expiresAt;
				console.log("new token", delegatedToken);
				console.log("new token expires", tokenExpiry);
				var tokenVideoIdJson = {"token": delegatedToken,
										"expires":tokenExpiry,
										"videoId": videoId};
				res.setHeader('Content-Type', 'application/json');
				res.end(JSON.stringify(tokenVideoIdJson));

			});
```

Once these two requests have been made, we then send back a JSON response to the browser with the ```videoId```, and the delegated token information.

### Token Expiration

The token expires in 90 seconds - how can we ensure that the video will upload completely in 90s? The answer is that we cannot.  However, we'll use a trick.  If we break the video to be uploaded into small segments, we just need to ensure that the first *segment* of the video is uploaded in 90s. The chunkSize is set to 6 MB - so the first 6 MB must be uploaded in 90s.  

> We're balancing your customers' upload speed with the expiry of the upload token.  If 6 MB in 90s is causing failures - you can lengthen the token expiry - the minimum upload size is 5 MB.  
> If you think this is too generous - lower the tokenTTL. 


### Video Upload

>NOTE: Since this post was written, we've published a library to simplify JavaScript upload of videos [read the blog post to learn more](https://api.video/blog/tutorials/new-video-uploader-javascript-library).


Now we can come back to the JavaScript on the page, and the ```qReq.onload``` that I omitted above:



First we grab the parameters sent from the Node server. For the purposes of the demo, we display the delegated tokenId and the time the token expires (in GMT) on the page.

We then create the delegated video upload url by appending the token to the base url. We determine the number of chunks to upload, and the initial byterange (0-chunkSize) and send the videoId and the videoFile to the createChunk function.

The createChunk function slices up the video from 0 to chunkEnd-1 (the file Slice API lists the first byte IN the slice, and the first byte NOT in the slice). *It's easy to get an off by one error here!*

```
			function createChunk(videoId, start, end){
				chunkCounter++;
				console.log("created chunk: ", chunkCounter);
				chunkEnd = Math.min(start + chunkSize , file.size );
				const chunk = file.slice(start, chunkEnd);
				console.log("i created a chunk of video" + start + "-" + chunkEnd + "minus 1	");
				const chunkForm = new FormData();
				console.log("createChunk videoId",videoId +start+end);
				if(videoId.length >0){
					//we have a videoId
					chunkForm.append('videoId', videoId);
					console.log("added videoId");	
					
				}
				chunkForm.append('file', chunk, filename);
				console.log("added file");

				
				//created the chunk, now upload iit
				uploadChunk(chunkForm, start, chunkEnd);
			}
```

Then the api calls the uploadChunk function that sets the byterange header (off by one warning!) and uploads the video.  It also updates the upload progress.  When the segment is completed, the counter is incremented, and calls the createChunk function again:

```
function uploadChunk(chunkForm, start, chunkEnd){
				var oReq = new XMLHttpRequest();
				oReq.upload.addEventListener("progress", updateProgress);	
				oReq.open("POST", url, true);
				var blobEnd = chunkEnd-1;
				var contentRange = "bytes "+ start+"-"+ blobEnd+"/"+file.size;
				oReq.setRequestHeader("Content-Range",contentRange);
				console.log("Content-Range", contentRange);
				function updateProgress (oEvent) {
					if (oEvent.lengthComputable) {  
					var percentComplete = Math.round(oEvent.loaded / oEvent.total * 100);
					
					var totalPercentComplete = Math.round((chunkCounter -1)/numberofChunks*100 +percentComplete/numberofChunks);
					document.getElementById("chunk-information").innerHTML = "Chunk # " + chunkCounter + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
				//	console.log (percentComplete);
					// ...
				} else {
					console.log ("not computable");
					// Unable to compute progress information since the total size is unknown
				}
				}
				oReq.onload = function (oEvent) {
							// Uploaded.
								console.log("uploaded chunk" );
								console.log("oReq.response", oReq.response);
								var resp = JSON.parse(oReq.response)
								videoId = resp.videoId;
								//playerUrl = resp.assets.player;
								console.log("videoId",videoId);
								
								//now we have the video ID - loop through and add the remaining chunks
								//we start one chunk in, as we have uploaded the first one.
								//next chunk starts at + chunkSize from start
								start += chunkSize;	
								//if start is smaller than file size - we have more to still upload
								if(start<file.size){
									//create the new chunk
									createChunk(videoId, start);
								}
								else{
									//the video is fully uploaded. there will now be a url in the response
									playerUrl = resp.assets.player;
									console.log("all uploaded! Watch here: ",playerUrl ) ;
									document.getElementById("video-information").innerHTML = "all uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a>" ;

								}
								
				};
				oReq.send(chunkForm);
		
				
				
			}
```


These two functions dance back and forth - creating slices and uploading them - until the entire video is uploaded.  When the video is fully uploaded, api.video begins assembling the video, and encoding the file.  The response conatains the player URL for the video - which we put on the page for the viewer to see. If the video is set to private - it will be a private URL with a token - only good for one view.

## Private and secure video upload

I think we've done it!  A single use public token for video upload, and the ability to protect the video **before** it is uploaded.

Now you can be sure that your users will properly "stay on the path" with their video uploads.

large_img20200822121759.jpg

medium_img20200822121759.jpg

small_img20200822121759.jpg

thumbnail_img20200822121759.jpg

img20200822121759.jpg

 The code is availabe on [Github](https://github.com/dougsillars/privatedelegatedtoken) if you'd like to take a deeper dive, or create your own version.  And don't forget to try the demo [privatelyupload.a.video](https://privatelyupload.a.video/).

Was this tutorial/demo app useful to you?  Do you have other examples of how to use api.video that you'd live to see? Let us know in our [community](https://community.api.video) forum. 

medium_footpath.jpg

small_footpath.jpg

thumbnail_footpath.jpg

footpath.jpg

Private video upload with a public token

Private Live

JavaScript

api.video offers a number of simple APIs to create and share video.  To protect videos from being shared, we offer the concept of private videos - where the ```public``` token for the video is set to ```false```.

These [private videos](https://api.video/blog/tutorials/tutorial-private-videos) have a URL token that can be used just once, and cannot be shared. To authenticate the token, we insert a custom header that must also be validated with the URL token.

If you use the api.video player - there is no development required - we do all the lifting of adding the authentication header for you.

If you are using a different player, you need to recieve this header from cdn.api.video and insert this header on each subsequent request.  To learn how, read on!

## Retrieving the header

For each unique view of a private video, you must generate a unique URL token.  It will look something like this:

>https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?token=c7cc5f68-1c98-49a0-a1c3-406e95d95228

Using Chrome DevTools, we can see what happens when we request this url:





large_picture-of-requests-in-chrome-devtools.png

medium_picture-of-requests-in-chrome-devtools.png

small_picture-of-requests-in-chrome-devtools.png

thumbnail_picture-of-requests-in-chrome-devtools.png

picture-of-requests-in-chrome-devtools.png

The 4th request is to cdn.api.video for the player.json.  The first request to this domain for a private video (either for the .mp4, the player.json, or the manifest.m3u8) will have a custom header in the response (```X-Token-Session```).


medium_x-token-session-in-headers.png

small_x-token-session-in-headers.png

thumbnail_x-token-session-in-headers.png

x-token-session-in-headers.png


This header and value must be sent on every subsequent request to cdn.api.video to ensure playback.

If you use the api.video player, each subsequent request has this header added  automatically.  For example, here is the request for the video thumbnail.jpg (in Safari, with a different session token):

request for the video thumbnail.jpg (in Safari)

large_request-for-the-video-thumbnail-jpg-in-safari.png

medium_request-for-the-video-thumbnail-jpg-in-safari.png

small_request-for-the-video-thumbnail-jpg-in-safari.png

thumbnail_request-for-the-video-thumbnail-jpg-in-safari.png

request-for-the-video-thumbnail-jpg-in-safari.png

At the bottom of the header list is the ```X-Token-Session```. 

## Using a different player

With a different video player, the code to insert this custom header must be added.  So lets walk through the steps to add a new request header in your code.

### Getting the session header

To retrieve the session header, simply request the first file from api.video (typically this is the m3u8 manifest file). It will look something like:

```
https://cdn.api.video/vod/vitkytkieTnEvUjKE0VQpd2/token/8e19097c-8310-4ce3-acba-206378119bc5/hls/manifest.m3u8
```

If you request this file from your player (or you can test just by loading this url in Safari), you'll receive the response with a lot of headers:

```
Timing-Allow-Origin: *
Cache-Control: no-store, no-store
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Content-Length: 590
Via: 1.1 PSfgblPAR2xf192:2 (W), 1.1 PSygldLON4zd14:8 (W), 1.1 PSygldLON2ew56:2 (W)
X-XSS-Protection: 1; mode=block, 1; mode=block
Date: Fri, 23 Oct 2020 10:02:57 GMT
Access-Control-Expose-Headers: Content-Type, Content-Length, Content-Range, X-Token-Session, Vary, Origin
X-Frame-Options: SAMEORIGIN, SAMEORIGIN
Access-Control-Allow-Credentials: true
Content-Type: application/vnd.apple.mpegurl
ETag: "5e8f75e8-24e"
X-Content-Type-Options: nosniff, nosniff
Last-Modified: Thu, 09 Apr 2020 19:22:16 GMT
x-proxy-cache: HIT
Server: PWS/8.3.1.0.8
x-ws-request-id: 5f92aa50_PSygldLON2ew56_14724-24181
x-token-session: 284a505f-d556-4de5-9498-c68260927551
x-px: ms PSygldLON2ew56LHR,ms PSygldLON4zd14LHR,ms PSfgblPAR2xf192CDG(origin)
```

Now we have the x-token-session for the playback of the video, and we must include this in each subsequent request.

### Minimal working example

The following piece of code shows how to retrieve the source file of a private video from a token value (error handling has been omitted for readability reasons).


## Adding the token to your header


Depending on the type of resource to retrieve, adding the X-Token-Session header may not be as straightforward as in the example above.

Below are some tips that you might find useful.

### Using MediaSource capabilities

If you manage the video tag yourself, you can use the [MediaSource interface](https://developer.mozilla.org/fr/docs/Web/API/MediaSource) to add headers to video files related requests.

### Using URL.createObjectURL() method

[URL.createObjectURL](https://developer.mozilla.org/fr/docs/Web/API/URL/createObjectURL) might be useful for some kinds of assets. For instance, you could display a video poster using an img tag with the following code:


### Using a service worker

[Service workers](https://developer.mozilla.org/fr/docs/Web/API/Service_Worker_API) can be used to intercept and modify any request made by your application and thus it gives you the ability to add headers. 


### Using video.js based players

If your player is based on [video.js player framework](https://videojs.com/), you can redefine the beforeRequest method on the xhr object of videojs.Hls . This will give you the ability to add the header on any video request. 


If you have any questions about this tutorial or would like to learn more about api.video please join our [community forum](https://community.api.video/). 

large_inserting-custom-headers.jpg

medium_inserting-custom-headers.jpg

small_inserting-custom-headers.jpg

thumbnail_inserting-custom-headers.jpg

inserting-custom-headers.jpg

Inserting custom headers

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](https://api.video/blog/tutorials/video-upload-tutorial) with api.video, the video is public, meaning that anyone with the link to the video can watch it, like the video below:

<iframe src="https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27"  height="540px" frameborder="0" scrolling="no" allowfullscreen=""></iframe>

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](https://docs.api.video/reference/get_upload-tokens).

## 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:

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](https://api.video/blog/tutorials/authentication-tutorial) with api.video. Next, make a request for the video:

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

Here is a snip of the JSON response:

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](https://api.video/blog/tutorials/inserting-custom-headers).


medium_private-videos-sequence-diagram.png

small_private-videos-sequence-diagram.png

thumbnail_private-videos-sequence-diagram.png

private-videos-sequence-diagram.png



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>```.

## Conclusion

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](https://community.api.video/). If you are ready to start building with api.video now, create your account [here](https://dashboard.api.video/register). Thank you for reading! 

large_privatevideo.png

medium_privatevideo.png

small_privatevideo.png

thumbnail_privatevideo.png

privatevideo.png

Creating private videos

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.