# Claves de firma | Docs de AudioDN

> Firma URLs de entrega en tu propio servidor con un secreto HMAC de alcance de organización, omitiendo las sesiones de reproducción para pistas públicas.

Source: https://audiodeliverynetwork.com/es/docs/api/signing-keys/

---

# Claves de firma

Una Signing Key es un secreto HMAC por organización que te permite firmar URLs de entrega directamente en tu propio servidor — sin sesión de reproducción, sin cabecera Authorization, sin round trip a la API de AudioDN. Las solicitudes van directamente a tu dominio de entrega (`{organization_id}.audiodelivery.net`), donde AudioDN verifica la firma en el edge y sirve tu audio. Ideal para pistas disponibles públicamente donde tú controlas quién recibe un enlace.

#### Acceso público

Cualquiera con una URL firmada válida puede reproducir el archivo hasta que caduque la firma. Mantén la firma en tu servidor, elige una duración de firma razonable y elimina las claves que ya no uses. Cada solicitud cuenta para el uso de reproducción y la facturación.

## Crear una Signing Key

En el [panel de AudioDN](https://account.audiodeliverynetwork.com), 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.

#### Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `title` | string | Obligatorio | Un nombre para identificar la clave |
| `ttl` | number | Opcional | Duración de la firma en segundos (predeterminado 10800 = 3 horas). Debe coincidir con el valor usado al firmar. |
| `variants` | string\[\] | Opcional | Restringir la clave a índices de variante concretos (p. ej. \["lq","hq"\]). Una clave sin variantes puede firmar cualquier archivo de tu dominio. |

## 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](https://account.audiodeliverynetwork.com) 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.

#### El uso y la facturación siguen aplicando

Como cada solicitud firmada es una entrega real, cuenta para tu uso de reproducción y facturación igual que un stream de sesión de reproducción. Elige una duración de firma razonable y elimina las claves que ya no uses para mantener el control del acceso.