JWT keys

JWT keys

There needs to be a way for us to know you trust the viewer when a private video is requested and so we support the industry-standard JWT (JSON Web Token).

If you have a video whose privacy is set to private then a valid cookie or JWT is required to be sent along with the request for its landing page / embed code / HLS manifest:

A cookie is generally sent when the video is embedded on our site. That usually means our dashboard (which enables private content to be managed within our system without us needing to know your private key).

A JWT is sent when the video is embedded on your site. In order for only you to be able to create a valid JWT, you need to diigitally sign it with a key. That is what this API endpoint is used for: it tells us your public key (half of your public/private key-pair).

For more information about how you make that JWT (its expected header and payload), please see our support page: How do I use a JWT to authenticate private videos.

Generate a JWT public key

Before you can tell us your public key, you need to make one (if you don't already have one). We don't currently have an API endpoint to generate one for you so you will need to make one on your local computer.

The exact commands to do that will vary depending on your system (please get in touch if not sure). On Mac/Linux you can create a key pair using these commands:

openssl genrsa -out privatekey.pem 2048
openssl rsa -in privatekey.pem -pubout -out publickey.pem

You will now have a private key privatekey.pem and a public key publickey.pem in the same folder you run those commands in:

cat privatekey.pem
cat publickey.pem

You keep the private key. Keep that safe and secret. You'll use that to digitally sign your JWT.

You provide us with the contents of your public key. That will look something like this, very long, with 'PUBLIC' quite clearly in the first line:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkq...
-----END PUBLIC KEY-----

You can now manage your JWT keys by making the following requests:

RequestDescription
GET /jwt_keysReturn the details of all of the JWT keys in your account
GET /jwt_keys/:idReturn the details of a single JWT key
DELETE /jwt_keys/:idDelete a JWT key
POST /jwt_keysCreate a JWT key

GET /jwt_keys

Return the details of all of the JWT keys in your account.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/jwt_keys"

Example response

{
"success": true,
"result": [
{
"id": "abcde12345abcde12345a",
"name": "Example key",
"public_key": "-----BEGIN PUBLIC KEY-----...",
"created_by": "abcde12345abcde12345a",
"created_time": "2021-01-01T12:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-01-01T12:00:00.000Z"
},
...
],
"links": {},
"errors": []
}

Optional parameters

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""Used to get the next page of results: if applicable we return this as part of the links.next URL

GET /jwt_keys/:id

Return the details of a single JWT key.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/jwt_keys/abcde12345abcde12345a"

Example response

{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "Example key",
"public_key": "-----BEGIN PUBLIC KEY-----...",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
"links": null,
"errors": []
}

Response format

KeyTypeDescription
idStringThe unique identifier given to this JWT key
nameStringThe name given to this JWT key
public_keyStringThe public half of the private/public key-pair you create: the certificate used to verify the JWT
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe date and time it was last modified

DELETE /jwt_keys/:id

Delete a JWT key.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/jwt_keys/abcde12345abcde12345a"

Example response

{
"success": true,
"result": {},
"links": null,
"errors": []
}

POST /jwt_keys

Create a JWT key.

Example request

curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"New key", "public_key": "----- BEGIN PUBLIC KEY -----\nMIIII..."}' \
"https://api.vidbeo.com/v2/jwt_keys"

Example response

{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "New key",
"public_key": "-----BEGIN PUBLIC KEY-----...",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
"links": null,
"errors": []
}

Required parameters

You need to give the new JWT key a name and send its public_key.

KeyTypeDescription
nameStringA name for the JWT key (1-50 characters)
public_keyStringThe public part of your private/public key pair