Signing Keys

Signing Key erstellen

Gehen Sie im AudioDN-Dashboard zu Settings → API Keys und erstellen Sie einen URL Signing-Key. Das Geheimnis wird Ihnen einmal angezeigt — speichern Sie es sicher auf Ihrem Server. Optional können Sie eine Signaturlebensdauer setzen und den Key auf bestimmte Varianten beschränken.

So funktioniert es

• Wenn Sie einen Key erstellen, registriert AudioDN Ihr Signing-Geheimnis am Edge, beschränkt auf Ihre Delivery-Domain ({org}.audiodelivery.net). Das Klartext-Geheimnis wird Ihnen einmal gezeigt und nie so gespeichert, dass es zurückgelesen werden kann.
• Auf Ihrem Server berechnen Sie ein HMAC-SHA256-Token über den Anfragepfad (und die Query-Zeichenkette) plus den aktuellen Zeitstempel und hängen es als Query-Parameter verify an.
• Wenn die Anfrage Ihre Delivery-Domain erreicht, berechnet AudioDN das HMAC aus Ihrem Geheimnis neu und bestätigt, dass es übereinstimmt und der Zeitstempel noch innerhalb der Signaturlebensdauer liegt. Gültige, nicht abgelaufene Anfragen werden sofort ausgeliefert.
• Ungültige oder abgelaufene Signaturen fallen auf den Standardschutz (den normalen Wiedergabesession-Flow) zurück und werden abgelehnt.

Die Verifikation nutzt das Standard-Timed-HMAC-Schema (is_timed_hmac_valid_v0), sodass jede HMAC-SHA256-Implementierung, die das URL-Format unten erzeugt, validiert wird.

Ihre Delivery-Domain

Jede Organisation erhält eine dedizierte Delivery-Subdomain der Form {organization_id}.audiodelivery.net, auf der AudioDN das Audio Ihrer Organisation ausliefert. Das ist der Host, gegen den Sie signieren, und der Host, von dem Ihre Nutzer Audio abrufen. Sie finden und kopieren Ihre genaue Domain im AudioDN-Dashboard unter Settings → Organization → Delivery Domain.

Die vollständige URL einer Datei ist Ihre Delivery-Domain plus der Dateipfad, zum Beispiel:

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

Format der signierten URL

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

issued ist der Unix-Zeitstempel (Sekunden) zum Zeitpunkt der Signierung. {base64url_mac} ist das URL-sichere Base64-HMAC (ohne Padding). Der Parameter verify muss immer zuletzt stehen.

Signieren auf Ihrem Server

Die Nachricht, die Sie signieren, ist der URL-Pfad plus eine vorhandene Query-Zeichenkette (ohne verify), gefolgt vom Zeitstempel. Diese Referenzimplementierung nutzt die Web Crypto API und funktioniert in Node 18+, Deno, Bun, den meisten Edge-Runtimes und im Browser:

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();
}

Die Signaturlebensdauer wird am Edge erzwungen (der ttl, den Sie beim Erstellen des Keys setzen), daher betten Sie kein Ablaufdatum ein — nur den Issued-Zeitstempel.

Varianten-Geltungsbereich

Wenn Sie einen Key auf bestimmte Varianten beschränken, akzeptiert der Edge nur Signaturen für Dateien, deren Pfad ein erlaubtes Varianten-Suffix enthält. Dateien heißen {track_index}_{variant_index}.{ext} und liegen unter {folder_id}/{file_name}, daher enthält eine Anfrage für die Variante lq immer _lq. im Pfad. Für andere Varianten signierte Anfragen fallen auf den Standardschutz zurück und werden abgelehnt.

Plays & Reporting

Signierte URLs liefern Audio direkt von Ihrer Delivery-Domain und umgehen die Wiedergabesession — es gibt keinen Aufruf der AudioDN-API zum Erzeugen eines Session-Tokens und keinen Autorisierungs-Roundtrip pro Play. Das macht sie schnell und einfach für öffentliche Tracks.

Auch wenn die Wiedergabesession umgangen wird, bleiben Ihre Play-Statistiken korrekt. Plays in Ihrem Reporting-Dashboard werden aus der tatsächlichen Audioauslieferung auf Ihrer Domain gemessen, stündlich aggregiert. Ob eine Datei über eine Wiedergabesession oder eine serverseitig signierte HMAC-URL abgerufen wird — die zugrunde liegende Auslieferung ist dieselbe, daher werden beide gezählt.