Clés de signature

Créer une clé de signature

Dans le tableau de bord AudioDN, allez dans Settings → API Keys et créez une clé URL Signing. Le secret vous sera montré une seule fois — stockez-le en sécurité sur votre serveur. Vous pouvez optionnellement définir une durée de vie de signature et limiter la clé à des variantes spécifiques.

Fonctionnement

• Lorsque vous créez une clé, AudioDN enregistre votre secret de signature en périphérie, limité à votre domaine de livraison ({org}.audiodelivery.net). Le secret en clair vous est montré une fois et n’est jamais stocké de façon à pouvoir être relu.
• Sur votre serveur, vous calculez un jeton HMAC-SHA256 sur le chemin de la requête (et la chaîne de requête) plus l’horodatage actuel, puis vous l’ajoutez comme paramètre de requête verify.
• Lorsque la requête atteint votre domaine de livraison, AudioDN recalcule le HMAC à partir de votre secret et confirme qu’il correspond et que l’horodatage est encore dans la durée de vie de la signature. Les requêtes valides et non expirées sont servies immédiatement.
• Les signatures invalides ou expirées basculent vers la protection standard (le flux normal de session de lecture) et sont rejetées.

La vérification utilise le schéma HMAC temporisé standard (is_timed_hmac_valid_v0), donc toute implémentation HMAC-SHA256 qui produit le format d’URL ci-dessous sera validée.

Votre domaine de livraison

Chaque organisation obtient un sous-domaine de livraison dédié de la forme {organization_id}.audiodelivery.net, où AudioDN sert l’audio de votre organisation. C’est l’hôte contre lequel vous signez et l’hôte depuis lequel vos utilisateurs récupèrent l’audio. Vous pouvez trouver et copier votre domaine exact dans le tableau de bord AudioDN sous Settings → Organization → Delivery Domain.

L’URL complète d’un fichier est votre domaine de livraison plus le chemin du fichier, par exemple :

https://1bb2f0c4-....audiodelivery.net/7e4386f0-..../20260709145408659.uSYrzmRWTDvEyjFz_lq.aac

Format de l’URL signée

https://{org_domain}/{file_path}?verify={issued}-{base64url_mac}

issued est l’horodatage Unix (secondes) au moment de la signature. {base64url_mac} est le HMAC en Base64 URL-safe (sans padding). Le paramètre verify doit toujours être en dernier.

Signer sur votre serveur

Le message que vous signez est le chemin de l’URL plus toute chaîne de requête existante (en excluant verify), suivi de l’horodatage. Cette implémentation de référence utilise l’API Web Crypto et fonctionne dans Node 18+, Deno, Bun, la plupart des runtimes en périphérie, et le navigateur :

function base64url(bytes) {
let binary = '';
const b = new Uint8Array(bytes);
for (let i = 0; i < b.byteLength; i++) binary += String.fromCharCode(b[i]);
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

async function hmacSha256(key, data) {
const cryptoKey = await crypto.subtle.importKey(
  'raw', new TextEncoder().encode(key),
  { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
);
return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, new TextEncoder().encode(data)));
}

// secret  = the signing key secret from the dashboard
// domain  = your org delivery host, e.g. "1bb2....audiodelivery.net"
// path    = the file path on your delivery domain, e.g. "folder-id/track-index_lq.mp3"
async function signUrl(secret, domain, path) {
const u = new URL('https://' + domain + '/' + path);
u.searchParams.delete('verify');

const message = u.pathname + (u.search || '');
const issued = Math.floor(Date.now() / 1000).toString();

const mac = await hmacSha256(secret, message + issued);
u.searchParams.append('verify', issued + '-' + base64url(mac)); // verify MUST be last

return u.toString();
}

La durée de vie de la signature est appliquée en périphérie (le ttl que vous définissez à la création de la clé), donc vous n’intégrez pas d’expiration — uniquement l’horodatage d’émission.

Portée des variantes

Lorsque vous limitez une clé à des variantes spécifiques, la périphérie n’accepte les signatures que pour les fichiers dont le chemin contient un suffixe de variante autorisé. Les fichiers sont nommés {track_index}_{variant_index}.{ext} et stockés à {folder_id}/{file_name}, donc une requête pour la variante lq contient toujours _lq. dans son chemin. Les requêtes signées pour toute autre variante basculent vers la protection standard et sont rejetées.

Lectures et rapports

Les URL signées livrent l’audio directement depuis votre domaine de livraison et contournent la session de lecture — il n’y a pas d’appel à l’API AudioDN pour générer un jeton de session, et pas d’aller-retour d’autorisation par lecture. C’est ce qui les rend rapides et simples pour les pistes publiques.

Même si la session de lecture est contournée, vos statistiques de lecture restent exactes. Les lectures dans votre tableau de bord Reporting sont mesurées à partir de la livraison audio réelle sur votre domaine, agrégées à l’heure. Qu’un fichier soit récupéré via une session de lecture ou une URL HMAC signée côté serveur, la livraison sous-jacente est la même, donc les deux sont comptées.