Secure an MP3/AAC or HLS stream with a single key

This guide explains how to maintain control over your MP3/AAC or HLS radio streaming flows, for example, to decide if a listener can listen to your radio by enabling unique key protection (token).

Protect an audio stream with a unique key

The principle is simple: for each connection, you will make a request to the Infomaniak API, which will return a unique token with a limited and configurable lifespan. This token will allow anyone who possesses it to consume the stream during this period.

You can protect an MP3/AAC or HLS stream independently of each other (the same goes for geolocation).

To do this, simply go to the restriction settings and enable token protection on the stream you wish to secure:

1. log in to the Infomaniak Manager (manager.infomaniak.com) using a web browser such as Brave or Edge
2. click on the ‍ icon in the top right of the interface (or navigate using the left side menu, for example)
3. choose Radio Streaming (streaming universe)
4. click on the name of the relevant object in the table that appears
5. click on Restrictions in the left side menu
6. choose HLS if necessary
7. click on the action menu ⋮ to the right of the relevant stream in the displayed table
8. click on Token Restriction
   
    

Then activate the protection.

Note that once you activate this option, access to the stream will be instantly blocked for new connections. Adjust your players to account for the restriction, as illustrated in the example below:

Create a Radio API token

To access the Radio API, you must first authenticate using an application token. This step only needs to be done once. To create this application token, read this guide.

The scope is radio and the lifespan is unlimited to avoid having to regenerate a code regularly. Once the token is generated, copy it to paste it in the example below.

Usage Example in PHP

For MP3/AAC or HLS, the code can be essentially the same; only the URL called in POST changes in its form.

if (!defined('API_TOKEN')) {
     define('API_TOKEN', 'AYF5lSh3c7Xy5974Fs12RTkTThujT-L9R4Xk2ZfGyP6sV7QqJ1oC3jD8nFtKzIxUeMw5oNzR6');
}
/**
 * Generic function to execute cURL requests
 *
 * @param string $method HTTP method (GET, POST, PUT, etc...)
 * @param string $url URL of the API to query
 * @param array $headers List of HTTP headers (authorization must be passed here with a ['Authorization: Bearer ']
 * @param array $payload An array containing the data to create a token
 * @return mixed
 */

function request(string $method, string $url, array $headers = [], array $payload = []): mixed{
    // prepare options array
    $opts = [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_URL => $url,
        CURLOPT_CUSTOMREQUEST => strtoupper($method),
    ];

    // add payload if relevant
    if ($payload && $method !== 'GET') {
        $opts[CURLOPT_POSTFIELDS] = json_encode($payload);
    }
    $ch = curl_init();
    curl_setopt_array($ch, $opts);
    $result = curl_exec($ch);
    if(curl_errno($ch)){
        throw new Exception(curl_error($ch));
    }
    $data = json_decode($result, true);
    if ($data['result'] === 'error') {
        throw new Exception($data['error']['description'] ?? 'an error occurred');
    }
    return $data['data'];
}

We will create the token; the URL for creating the token breaks down as follows:

• For an MP3/AAC stream

POST https://api.infomaniak.com/1/radios/acl/streams/mountpoint.mp3/token

Example to protect https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac the route will be: https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token

• For an HLS stream

POST https://api.infomaniak.com/1/radios/acl/hls_streams//token

Example to protect https://myradiostream.radiohls.infomaniak.com/myradiostream/manifest.m3u8 the route will be: https://api.infomaniak.com/1/radios/acl/hls_streams/myradiostream/token

Example in the case of MP3/AAC, remember to adjust:

$token = request(
    'POST',
   'https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token',
    // authorization header
    [
        'Authorization: Bearer ' . API_TOKEN,
        'Content-Type: application/json',
    ],
    /**
     * payload to create the token, you can pass the following values
     * window      | 300                | optional | validity duration of the token (default: 5 minutes)
     */

    [
        'window' => 3600, // 1h validity
    ]
);

It is important to note that if this code is generated at the time of page loading, the listener will have "window" seconds to start playback of the stream. Beyond this delay, the token will expire, and the stream can no longer be started unless the page is reloaded. Depending on your needs and use case, it will be necessary to adjust this delay in the best possible way.

You will also need to replace the playback URL of your stream below with the one indicated while keeping the $token parameter at the end. Finally, we display the player (here a simple HTML5 tag, but you can add any overlay afterwards, as the token is passed in the $_GET parameters of the URL).

$streamUrl = "https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac?$token";
echo "<audio controls=""><source src="$streamUrl"></audio>";