This guide explains how to maintain control over your MP3/AAC or HLS Radio Streaming streams by activating unique key (token) protection to decide, for example, whether a listener can listen to your radio or not.

Preamble

• The principle is simple: with 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 authorize 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 applies to geolocation).
• Activating the restriction involves changing the stream configuration, which may take a few minutes to be replicated on the servers.

Protect an audio stream with a unique key

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

1. Click here to access the management of your product on the Infomaniak Manager (need help?).
2. Click directly on the name assigned to the product concerned.
3. Click on the name of the audio stream concerned.
4. Click on Restrictions in the left sidebar.
5. Choose HLS if necessary.
6. Click on the action menu ⋮ located to the right of the item concerned.
7. Click on Token Restriction:
   
    

Then activate the protection.

Warning, at the moment you activate this option, access to the stream will be instantly blocked for new connections. Adapt your Players to take into account 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, refer to this other guide.

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

Example of use in PHP language

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

if (!defined('API_TOKEN')) {
     define('API_TOKEN', 'AYF5lSh3c7Xy5974Fs12RTkTThujT-L9R4Xk2ZfGyP6sV7QqJ1oC3jD8nFtKzIxUeMw5oNzR6');
}
/**
 * Fonction générique pour executer des requêtes cURL
 *
 * @param string $method Méthode HTTP (GET, POST, PUT, etc...)
 * @param string $url Url de l'api a requêter
 * @param array $headers Liste des en-têtes HTTP (l'autorisation doit être passée ici avec un ['Authorization: Bearer ']
 * @param array $payload Un tableau contenant les données pour créer un 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 occured');

    }
    return $data['data'];
}

We are going to create the token, the URL for creating the token is broken 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/<stream>/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',
    // en-tête d'authorization
    [
        'Authorization: Bearer ' . API_TOKEN,
        'Content-Type: application/json',
    ],
    /**
     * payload pour créer le token, vous pouvez passer les valeurs suivantes
     * window     | 300               | optionnel | durée de validité du 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 playing the stream. Beyond this deadline, the token will expire, and the stream will no longer be able to 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 parameter $token at the end. And finally, we display the Player (here a simple html5 tag, but you can of course add any overlay afterwards, the token being passed in the parameters $_GET of the url).

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