Claves de firma

Crear una Signing Key

En el panel de AudioDN, ve a Settings → API Keys y crea una clave URL Signing. Se te mostrará el secreto una sola vez — guárdalo de forma segura en tu servidor. Opcionalmente puedes establecer una duración de firma y limitar la clave a variantes concretas.

Cómo funciona

• Al crear una clave, AudioDN registra tu secreto de firma en el edge, con alcance a tu dominio de entrega ({org}.audiodelivery.net). El secreto en texto plano se te muestra una vez y nunca se almacena donde se pueda leer de nuevo.
• En tu servidor, calculas un token HMAC-SHA256 sobre la ruta de la solicitud (y la query string) más la marca de tiempo actual, y lo añades como parámetro de query verify.
• Cuando la solicitud llega a tu dominio de entrega, AudioDN recalcula el HMAC con tu secreto y confirma que coincide y que la marca de tiempo sigue dentro de la duración de la firma. Las solicitudes válidas y no caducadas se sirven de inmediato.
• Las firmas no válidas o caducadas caen en la protección estándar (el flujo normal de sesión de reproducción) y se rechazan.

La verificación usa el esquema estándar de HMAC temporizado (is_timed_hmac_valid_v0), así que cualquier implementación HMAC-SHA256 que produzca el formato de URL siguiente validará.

Tu dominio de entrega

Cada organización obtiene un subdominio de entrega dedicado con la forma {organization_id}.audiodelivery.net, donde AudioDN sirve el audio de tu organización. Este es el host contra el que firmas y el host desde el que tus usuarios obtienen el audio. Puedes encontrar y copiar tu dominio exacto en el panel de AudioDN bajo Settings → Organization → Delivery Domain.

La URL completa de un archivo es tu dominio de entrega más la ruta del archivo, por ejemplo:

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

Formato de URL firmada

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

issued es la marca de tiempo Unix (segundos) en la que firmaste. {base64url_mac} es el HMAC en Base64 seguro para URL (sin padding). El parámetro verify debe ir siempre al final.

Firmar en tu servidor

El mensaje que firmas es la ruta de la URL más cualquier query string existente (excluyendo verify), seguido de la marca de tiempo. Esta implementación de referencia usa la Web Crypto API y funciona en Node 18+, Deno, Bun, la mayoría de runtimes de edge y el navegador:

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 duración de la firma se aplica en el edge (el ttl que estableciste al crear la clave), así que no incrustas una caducidad — solo la marca de tiempo de emisión.

Alcance por variante

Cuando limitas una clave a variantes concretas, el edge solo acepta firmas de archivos cuya ruta contenga un sufijo de variante permitido. Los archivos se nombran {track_index}_{variant_index}.{ext} y se almacenan en {folder_id}/{file_name}, así que una solicitud de la variante lq siempre contiene _lq. en su ruta. Las solicitudes firmadas para cualquier otra variante caen en la protección estándar y se rechazan.

Reproducciones e informes

Las URLs firmadas entregan audio directamente desde tu dominio de entrega y omiten la sesión de reproducción — no hay llamada a la API de AudioDN para generar un token de sesión, ni round trip de autorización por reproducción. Eso es lo que las hace rápidas y simples para pistas públicas.

Aunque se omita la sesión de reproducción, tus estadísticas de reproducción siguen siendo precisas. Las reproducciones en tu panel de Reporting se miden a partir de la entrega real de audio en tu dominio, agregadas por hora. Tanto si un archivo se obtiene a través de una sesión de reproducción como de una URL HMAC firmada en el servidor, la entrega subyacente es la misma, así que ambas se contabilizan.