Delegated uploads: Make video uploads with a token you create

September 16, 2020 - Doug Sillars in Delegated Upload, Authenticate

At api.video, we offer a number of ways to upload video into your account. When you create and upload a video, the first step is to authenticate with your API, and generate an authentication token.

For a static website, it may not be feasible to create a new token on each page load. For instances like these, we offer a delegated upload token. This token works like a public key to your api.video account, allowing secure uploads without exposing your API key.

Generating a Delegated Upload Token

The first step in creating a delegated upload is to generate your token. First we authenticate with your private key :

Note: I am using the sandbox API endpoint AND my sandbox API key in this example. To use production, point to https://ws.api.video, and use your production key.

curl --request POST  --url https://sandbox.api.video/auth/api-key  
--header 'accept: application/json' 
--header 'content-type: application/json'   
--data '{"apiKey":"{my sandbox api key"}'

This will return a JSON response with your authentication token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjkyODdhZjk1NmFjOTdlMmUwMjI0MjJhMzdjN2NlM2Q2MTBiZDcxMDIyOGMxMThjOTExOTM1YWYwNDY0ZjUyOGYyZWQ2NWEzOTU2MDMzYWY1In0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiOTI4N2FmOTU2YWM5N2UyZTAyMjQyMmEzN2M3Y2UzZDYxMGJkNzEwMjI4YzExOGM5MTE5MzVhZjA0NjRmNTI4ZjJlZDY1YTM5NTYwMzNhZjUiLCJpYXQiOjE2MDAyNTc0MzUsIm5iZiI6MTYwMDI1NzQzNSwiZXhwIjoxNjAwMjYxMDM1LCJzdWIiOiJDRldta3ZXbmJRNjdsVU9ZanRmeTFnYThBaE5WTXJRVDdWYWpVWnYwY3daIiwic2NvcGVzIjpbIiJdLCJjb250ZXh0Ijp7InVzZXJJZCI6bnVsbCwiZmVhdHVyZXMiOltdLCJtZW1iZXJJZCI6bnVsbCwicHJvamVjdElkIjoicHJVTXNlaG9FakNmYnp4bDFlZVYwMEkifX0.Ok9-LiITQ_xAaHG12mWtSojqnAcmpz2b2LTGQZ4bH9qSVifQzR6E4dht019ixsSiboJUloAG2W1OcnRra2usG0zAgOejsRZayoEpCY0hl0A3KPRgNKqtqs4F8uKD19ppDPhrM1PTavsMUp6kXiVjPNktkYyD4ljQ0Otu5GhPC4K3cVye_hY6Th3szV72Nt9uHdsLNHOPB-V65j1mnoQV9VuJvJypz23JjkRZQtu8Wvf5mp_htf5f1E8DfHTrGTx3wQcwFjR5k_6thQYxAIuCxCs-jFLXgKoSqr7r6BlgJ0IfFmaF8_1jz6nBzX7sBavxKR_OZKEfKsXXhGCdBzgykg

We’ll use this token to request the delegated upload token:

The delegated upload API will create a new token:

curl --request POST   --url https://sandbox.api.video/upload-tokens   
--header 'accept: application/vnd.api.video+json'
 --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjkyODdhZjk1NmFjOTdlMmUwMjI0MjJhMzdjN2NlM2Q2MTBiZDcxMDIyOGMxMThjOTExOTM1YWYwNDY0ZjUyOGYyZWQ2NWEzOTU2MDMzYWY1In0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiOTI4N2FmOTU2YWM5N2UyZTAyMjQyMmEzN2M3Y2UzZDYxMGJkNzEwMjI4YzExOGM5MTE5MzVhZjA0NjRmNTI4ZjJlZDY1YTM5NTYwMzNhZjUiLCJpYXQiOjE2MDAyNTc0MzUsIm5iZiI6MTYwMDI1NzQzNSwiZXhwIjoxNjAwMjYxMDM1LCJzdWIiOiJDRldta3ZXbmJRNjdsVU9ZanRmeTFnYThBaE5WTXJRVDdWYWpVWnYwY3daIiwic2NvcGVzIjpbIiJdLCJjb250ZXh0Ijp7InVzZXJJZCI6bnVsbCwiZmVhdHVyZXMiOltdLCJtZW1iZXJJZCI6bnVsbCwicHJvamVjdElkIjoicHJVTXNlaG9FakNmYnp4bDFlZVYwMEkifX0.Ok9-LiITQ_xAaHG12mWtSojqnAcmpz2b2LTGQZ4bH9qSVifQzR6E4dht019ixsSiboJUloAG2W1OcnRra2usG0zAgOejsRZayoEpCY0hl0A3KPRgNKqtqs4F8uKD19ppDPhrM1PTavsMUp6kXiVjPNktkYyD4ljQ0Otu5GhPC4K3cVye_hY6Th3szV72Nt9uHdsLNHOPB-V65j1mnoQV9VuJvJypz23JjkRZQtu8Wvf5mp_htf5f1E8DfHTrGTx3wQcwFjR5k_6thQYxAIuCxCs-jFLXgKoSqr7r6BlgJ0IfFmaF8_1jz6nBzX7sBavxKR_OZKEfKsXXhGCdBzgykg
}'

This will result in JSON response with the delegated access token:

{"token":"to1R5LOYV0091XN3GQva27OS"}

This token can now be used to upload videos into your api.video account. In the example below, I am uploading a video of clouds into my sandbox account.

curl --request POST --url 'https://sandbox.api.video/upload?token=to1R5LOYV0091XN3GQva27OS'
 --header 'content-type: multipart/form-data' 
-F file=@/Users/dougsillars/Documents/videoplayground/clouds.mp4

Go ahead and try this yourself! Since the delegated upload is into my sandbox account, the video will be watermarked and deleted after 72 hours. Simply point the -F file@ to a video on your local file system, and it will be uploaded into my sandbox.

You'll receive a response similar to this:

{
	"videoId": "vi3lK4OblSCH1KgXLY6bN5f0",
	"title": "clouds.mp4",
	"description": "",
	"public": true,
	"panoramic": false,
	"mp4Support": true,
	"publishedAt": "2020-09-16T12:06:54+00:00",
	"updatedAt": "2020-09-16T12:06:54+00:00",
	"tags": [

	],
	"metadata": [

	],
	"source": {
		"type": "upload",
		"uri": "/videos/vi3lK4OblSCH1KgXLY6bN5f0/source"
	},
	"assets": {
		"iframe": "<iframe src=\"https://embed.api.video/vod/vi3lK4OblSCH1KgXLY6bN5f0\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
		"player": "https://embed.api.video/vod/vi3lK4OblSCH1KgXLY6bN5f0",
		"hls": "https://cdn.api.video/vod/vi3lK4OblSCH1KgXLY6bN5f0/hls/manifest.m3u8",
		"thumbnail": "https://cdn.api.video/vod/vi3lK4OblSCH1KgXLY6bN5f0/thumbnail.jpg"
	}
}

These urls can be shared for others to watch your video. On opening the player link, you might see a video like this: (Note the video link in the JSON above has expired and will throw a 404 error).

Expiring Delegated tokens

Delegated tokens act like a public API - anyone with this token and the api.video url could upload videos into your account. For this reason, you can revoke delegated tokens so they can no longer be used.

Delegated Token Time To Live

In addition to expiration, you can also set a 'time to live' (TTL) when creating a token. Once the token expires, itc an no longer accept uploads. If you generate the token when the uplaod begins - you must ensure that at least one segment of the video is uploaded before the token expires, or the video will be rejected at the server. You can split the video with the JavaScript file API. Once the token expires, you'll have 24 hours to complete the rest of the upload (which should be PLENTY of time).