By default, access and sharing of your Stream are available to anyone who has knowledge of its URL. This intentional accessibility is designed to facilitate seamless content sharing and embedding. Nevertheless, there are instances where it's necessary to safeguard your content and exercise precise control over who can access your Streams and for what duration. This is where our "Signed URL" feature becomes pivotal, enabling you to secure your Streams by generating signed URLs.

For users to access a signed Stream, they must authenticate themselves by providing a signed [JSON Web Token](🔗) (JWT) with their request. This token needs to be generated and signed with a private encryption key exclusively known to you. Optionally, this token can include an "expiration" parameter that specifies the duration of access to the signed Stream.

## Getting Started:

### Create a new signing key

The first step is to create a signing key by making a`POST` request to the `/signing-keys` endpoint. This returns a base64 encoded private key in PEM format, which is required for signing your JSON Web Tokens.

Storing your signing key

Ensure the secure storage of your private key as we do not retain copies on our servers! If you happen to lose access to your private key, refer to the instructions provided in the **Key Rotation** section below to acquire a new private key.

### Create a signed Stream

To protect a Stream with a Signed URL, you must set the property `signed: true` when creating a new Stream. Please note that it is currently not possible to convert already existing Streams to utilize Signed URLs, nor can Signed URLs be converted back to the previous format.

Once a signed Stream is created, it cannot be accessed right away or be previewed in the Dashboard unless a JWT signed by you is provided.

### Creating a JSON Web Token

JSON Web Tokens are defined by an [open standard](🔗) and can be generated by various [third party libraries](🔗) in many different programming languages. A JWT is a JSON object containing metadata, such as the expiration time of your request, and is signed with an RSA private key known only to you. Bitmovin holds the corresponding public part of your RSA key pair and uses it to verify the token's authenticity. To learn more about JSON Web Tokens, refer to [this document](🔗).

By default, a signed Stream is valid for 5 hours. If you want to change that value you can [set the `exp` claim](🔗) in the JWT to a custom value. It is recommended to choose a duration longer than your Stream's length; otherwise, the signed URL will expire prematurely, preventing you from viewing the complete video.

### Add Token to Streams web component

Once a token has been generated, you must add it to the Streams web component by specifying the `token` parameter as follows:

Upon validation of the token, permission is granted for Stream access, initiating the playback.

## Available Endpoints

Streams provides the following endpoints for managing signing keys:

`POST /signing-keys`: Creates a new signing key pair and returns the private key in base64 encoding. Please note that there is a limit of 2 active signing keys per organization.

`GET /signing-keys`: Retrieves your public signing key ids.

`DELETE /signing-keys/{keyId}`: Deletes an existing signing key by id.

## Key Rotation

In case you forgot or accidentally exposed your private key, you can rotate your signing key by following these steps:

  1. Create a new signing key by visiting the `/signing-keys` POST endpoint. (Limited to 2 keys)

  2. Ensure that your new private key is set up and ready for use on your side.

  3. When you are confident that everything is ready with your new key, you can delete the old key via the `/signing-keys/{keyId}` `DELETE` endpoint.