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.
Authentication in the world of Lord of the Rings
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!
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.)
