You shall not pass: The benefits of token based authentication
api.video uses token based authentication in one way or another for every endpoint. See how our token based authenticated is implemented, what benefits this kind of authentication provides, and what simple best practices you can apply when working with tokens. Along the way, enjoy a few LOTR references!
Erikka Innes
February 24, 2021
api.video is a big fan of token based authentication, especially J.R.R token...just kidding, we use JWT tokens. While it's a little bit of extra work up front - you must provide your API key to our authentication endpoint https://ws.api.video/auth/api-key to retrieve a token - the benefits are well worth it. Today, we'll take a look at api.video's authentication mechanisms and review what makes token-based authentication an excellent choice for our API.
What is a Token?
Before we dig into token-based authentication, let's go over what a token is. A token is a self-contained piece of data that contains all the information it needs to authenticate with a system that supports tokens. They are stateless, meaning that they don't store details about what's happening with a client. If a client wants to send information about its state, it must be passed with the request in some other way.
There are many kinds of tokens, but api.video uses JWT (Json Web Tokens), delegated tokens, and UUID (universally unique identified, RFC 4122) tokens. Without getting too detailed, a JWT token is an open standard (RFC 7519) that provides a way to securely transmit information between parties as a JSON object. It is composed of three parts - a header, a payload and a signature. The header tells you what kind of token you have (JWT) and what algorithm you used to encode it. The header is base64url encoded.
The payload contains claims. Claims are statements and data about the user (usually) that you can use to identify the user. The payload is also base64url encoded. The signature is the encoded header, encoded payload, a secret, the algorithm specified in the header taken together and signed. After all the parts are assembled, you end up with a JWT token, which is broken into three parts - the header, payload, and signature. Each part is separated by a period. Someone on either end of the transaction can trust the information, because it is digitally signed with a secret. api.video uses signed JWTs. If you want more detail about what a JWT is, see jwt.io.
A delegated token in api.video's systems is 'to' + a random string. It doesn't have detail like a JWT. It's created by your request, after you successfully authenticate with a JWT. Once you succeed, you are issued a delegated token that allows limited privileges. These are used for video uploads.
UUID tokens are used for private viewing of VOD and live streams. A UUID token is a 128-bit number used to identify information in computer systems. It's a random string generated using the UUID algorithm. The only other information it sometimes contains besides the random string, is a timestamp. UUID is a good way of generating tokens because they are highly unlikely to generate the same UUID twice.
Now that we know a little bit about tokens, let's take a look at how they get used with api.video endpoints.
Authentication at api.video
Token-based authentication is where you verify your identity in some way, and then you receive a unique access token you can use to access resources. With api.video, we verify users by API key and by JWT. We use the API key to authenticate you and generate a JWT for use in bearer authentication. We use bearer authentication to grant access to services, and the ability to create delegated tokens. You can then use the delegated tokens with certain endpoints. We generate private UUID tokens for one-time viewings of video or live streams.
And if you wanted to see two ways you can handle authentication in Python (with and without our Python client) you can check out this informative video!
Benefit from token based authentication with api.video
Bearer Authentication
Bearer authentication is a specific type of token-based authentication. When you authenticate with your API key, we use the information you provide to create a JWT that's sent back to you in a response. The token you receive is a true JWT that lasts for one hour, and you can use it to access api.video services or create tokens for use with api.video services. You can create additional JWTs if you wish, each lasts for one hour.
You put your token in an authorization header for Bearer Authentication, like so: Authorization: Bearer 'your JWT token string'
This type of authentication is called Bearer authentication because it's understood as 'give access to the bearer of this token.'
The main advantages of a JWT are:
You don't have to expose your API credentials.
They don't require much space in memory.
They are stateless.
If there's a problem with a JWT, you can expire it and replace it with a new one.
You can create multiple JWTs at once, which you might need sometimes for different tasks or users.
Delegated Authentication
api.video uses token-based authentication where the token is not a JWT in:
Delegated uploads
Private tokens for viewing private videos and live streams
Delegated uploads use a custom delegated token. The style of authentication for this is sometimes referred to as 'delegated authentication.' The idea is that you can limit access with a delegated token while still making it possible for services or other users to take action on behalf of a user (you). Common features of delegated tokens are:
They rely on another system for authentication. (In our case, this would be the request you sent the JWT in. You send your JWT via bearer authentication, you are verified, then you get the token to use.)
They prevent access to all your privileges and credentials. If someone intercepts a delegated token, they don't get details about the user the token is issued on behalf of, and they can't access anything beyond what the token permits.
They can be easily controlled. You can create long or short lived tokens, and delete them when they're no longer useful. In the case of private tokens generated server side, api.video handles removing the tokens for you.
There are many ways to set these up, and delegated tokens don't necessarily include every feature listed. With api.video, delegated tokens are created by you sending a JWT via bearer authentication and requesting a token for use with a delegated upload. This token has a time-to-live that's selected by you, and its privileges are limited to the delegated endpoints.
The advantages of the delegated token include:
You can use it to restrict access to video content.
The tokens are more lightweight than a JWT, allowing faster transaction time. A JWT is about 304 bytes while api.video's delegated tokens are about 24 bytes each.
It's easier to scale. You can offer more people one-time use tokens because they take up much less space at 24 bytes each.
Someone can't pick apart a delegated or private token and obtain details about the user the token was created on behalf of.
Someone can't use the token for more than the privileges specified.
You can delete compromised tokens immediately.
Private Tokens
Private UUID tokens are created by api.video server side. They are created for one time use with a video on demand (VOD) or a live stream. The advantages of UUID tokens are:
They take very little space in memory. Every UUID token can be represented as a 128-bit integer, which takes up less space than a string of the same size. So like a delegated token, it's easier to scale with.
You can use it to restrict access.
It can't be picked apart to gather credential information - it's just the token, and maybe a timestamp.
It is unlikely you'll randomly generate the same UUID twice, avoiding the possibility of collisions.
It has its own standard - RFC4122.
How Does api.video Use Token-Based Authentication for Private Videos and Live Streams?
For private videos (VOD), you set up your video so the public setting is false. Then when a user wants to see it, you have your app send a request for the video by providing the videoId (and a JWT). The response contains links to the video and the links contain the token. Every request to see the video will generate a new URL with a unique token that is good for one viewing only. For private live streams, the process is the same.
URL tokens are great because you, the developer, never have to worry about security or token management. Each time you want someone to be able to view a private video or live stream, api.video generates your tokens for you. They're stored server side so they can't easily be tampered with, and they are deleted for you when they're no longer needed. This lets you focus on developing.
Each token lets one viewer watch a video or a live stream for one session. If they close their browser and try to come back with the same token URL they shall not pass. (It's not that dramatic, they can probably get a new viewing session depending on how you set your app up.)
What are the Benefits of Token Based Authentication?
Token based authentication is especially beneficial because tokens, whether they are delegated, UUID, or JWT are:
Efficient. Tokens make everything faster, because you don't store credentials. Everything a user needs to authenticate for an endpoint is contained in the token, and this is passed back and forth for each request. This also makes it simpler to scale out and add more users because storage requirements are lower. The degree to which they make things faster depends on the type of token you have.
Flexible. You can use tokens for a web application or a mobile application, and still get the same benefits for either.
Mobile-ready. Tokens support an easy-to-use mobile-ready backend. They are much easier to implement than cookies and allow you to control access.
Secure. Tokens don't store sensitive information, and they don't expose a user's credentials. Particularly with api.video, you use your API credentials to get a token, then you use this to generate other tokens you might need. You only pass your API key once, and everything is stored in your tokens. This makes it harder to compromise your credentials. This is great for mobile applications, where a common issue is figuring out how to store API credentials. With tokens, you don't need to worry. They're also easier to manage and implement than sessions, and unlike sessions, don't store things in your browser, which is potentially less secure.
Shareable. You can grant users one-time use tokens, or short lived tokens to complete particular tasks. Then, you can delete the tokens, or have them expire.
For items to do with speed, the JWT is slower, but this is still faster than other options, if you wondering how it can be listed alongside the others.
What are Best Practices for Token Based Authentication?
The basics for securely using token based authentication are:
Don't store sensitive or personal information in JWTs. JWTs can be intercepted and read.
Send tokens over a secure network.
Limit the number of tokens you create and manage to what you need. Use tokens until they expire before generating a new one, and if you must generate multiple tokens, make sure you have a way to track and remove them so they don't exist for longer than necessary.
Protect your tokens and protect your API key. While tokens can make it easier to keep your API key from being compromised, you should still take steps to ensure the key is appropriately safeguarded.
When possible, give your tokens an expiration. This helps secure your system since if a token is stolen, the hacker can't continue using it forever.
Sign up with api.video to use token based authentication
