What is API file access?
Through the API, it’s possible to retrieve direct URLs to your video files. You could use these URLs to download your videos, use a third-party player, or any number of use cases. There are two ways to access these files. The first way is to enable the insecure API File access setting on your account. The second is to use secure signed URLs.
Why enable API file access?
By default, the direct links to your videos files are protected to prevent access without using our video player. This protects your source files from unwanted downloads. If you need to access the direct video files for use outside of our player, you’ll need to enable API file access.
How to Enable Insecure API File Access
Warning: Once enabled, anyone with access to the direct video URL will have unrestricted access to that source file.
To enable API File Access, navigate to ‘Account Settings’ > ‘API’ and check the box for ‘Enable API file access.’ Click ‘Save API Settings’ once you are done.
Note: If you disable API File Access your URLs will revert back to their default protected state.
Signed API File Access
If you’d prefer to keep access to your files secure, you can access them using a signed URL. Here are the steps for creating that signature.
Note: Do not enable the insecure API file access option above if you are using Signed API file access.
1. Find the URL you wish to sign
A video’s URL will be returned in the array of video assets section of a video’s API response. For this example, we’ll use this URL: https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4
2. Generate the string to sign
To start, we must generate the base string that will be used to create the hash. The base string is composed of the following elements:
Request method: The request method in this case will always be GET
Host name: The host name in this case will always be api-files.sproutvideo.com
Request path: The request path is part of the URL after the host up to the first ? If the URL we are signing is https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4, the request path is /file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4
Sorted query parameters: First, we need to add the expiration parameter to the list of parameters. Typically, you would pick a time a few minutes or so in the future. The time you pick should be in UTC. The value should be represented as an integer number of seconds since the Epoch. For example, the time of May 02 2013, 10:21:43 PM (UTC) would be represented as 1367533243. Since this request doesn’t support any other query parameters, the expiration is all you need. The sorted query parameters for this example becomes: &expires=1367533243
Note: Ideally your system time should be synced using NTP or a similar protocol so your system uses the same time that SproutVideo’s system does.
Now that we have all of our components, we need to combine them into a single string formatted on multiple lines as shown below:
Request method Host name Request path Sorted query parameters
With our example URL above, the multi-line string would look like this:
GET api-files.sproutvideo.com /file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4 &expires=1367533243
Now that we have our string, it is time to sign it.
3. Calculating the signature
First you’ll need your API key to sign the string. You can find your API key here. Finally, the signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The details of the algorithm are explained in depth here, but thankfully there are implementations of HMAC-SHA1 available for every popular language. Ruby has the OpenSSL library and PHP has the hash_hmac function.
For example, the output given the example string and a signing key of 9ab4b003d47003df394191234c54506d is \xD7\xD0\x18r\xE6\xB8q\b\xA61\xC0k*m\x04H\xCF\x0F\xE2\x1C. That value, when converted to base64, is the signature for this request: 19AYcua4cQimMcBrKm0ESM8P4hw=
4. Building the final request URL
- First, take the original URL:
https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4. - Next add the expires parameter to the end like this:
https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4?expires=1367533243 - Finally URL encode the signature parameter and add that to the end of the URL like this:
https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4?expires=1367533243&signature=19AYcua4cQimMcBrKm0ESM8P4hw%3D
You can then use this URL to directly access your MP4 files.
