URL Firmati e Token di Embed

Ogni video su AVCaption ha un token di embed nel suo URL: https://avcaption.com/watch/{embed_token}. Il token è la credenziale d’accesso — chiunque abbia un token valido può riprodurre il video, chi non ce l’ha viene rifiutato.

Per contenuti gratuiti o pubblici generi un token per video e vive per sempre. Per contenuti a pagamento o gated generi token freschi per sessione autenticata via REST API.

Come funzionano i token

Un token è una stringa breve opaca (default 32 caratteri esadecimali). Lato server mappa a:

• L’ID del video
• Un identificatore di spettatore opzionale (usato per analytics e watermark dinamico)
• Un timestamp di scadenza
• Una lista di origini consentite (la tua whitelist di domini)
• Metadata di rate limit

Quando il player richiede una chiave di stream, il server valida il token, controlla la scadenza, controlla l’origine della richiesta, e solo allora emette la chiave AES-128 per il batch successivo.

Token per sessione via REST API

Per contenuti a pagamento, il pattern consigliato è:

1. L’utente accede alla tua applicazione.
2. La tua applicazione autentica l’utente contro il tuo DB.
3. La tua applicazione chiama la REST API di AVCaption: POST /api/v1/embed-token con {video_id, viewer_id, expires_in: 3600}.
4. AVCaption restituisce un token di embed monouso valido 1 ora.
5. Renderizzi l’iframe con quel token.
6. Il token scade; se l’utente ricarica, la tua app ne genera uno fresco.

Significa che un utente che copia l’URL dell’iframe e la condivide passa un token che scade entro un’ora — inutile per la ridistribuzione.

Whitelist di domini a livello di token

I token possono essere legati a origini specifiche. Un token emesso per app.example.com non funziona se incorporato su pirate-site.com. Il browser invia un header Referer alla richiesta della master playlist; AVCaption lo valida contro la whitelist e rifiuta di emettere chiavi.

Confronto con gli approcci a URL firmato

Alcune piattaforme usano URL firmati (query string firmate HMAC su ogni segmento). AVCaption usa token opachi che mappano lato server ai metadata di accesso. Trade-off:

• URL firmati — del tutto stateless, facili da verificare all’edge. Ma una volta firmato un URL, non si può revocare prima della scadenza.
• Token opachi (AVCaption) — richiedono lookup lato server per sessione di stream, ma abilitano revoca in tempo reale, analytics per token e metadata di accesso più ricchi.

Per contenuti a pagamento dove la revoca conta, vincono i token opachi. Vedi la voce di glossario embed token vs URL firmato per un confronto più approfondito.

Rotazione dei token

Per contenuti di valore molto alto, ruota i token via API su un piano:

POST /api/v1/embed-token/rotate
{ "video_id": "abc123" }

Invalida tutti i token esistenti per quel video e ne emette uno nuovo. Utile dopo un sospetto leak o un chargeback.

Per iniziare

I token di embed vengono emessi automaticamente a ogni upload, su tutti i piani. La REST API per la generazione di token per sessione è una funzionalità Enterprise. Registrati. Pattern comuni: token per sessione per corsi online e video per membership site.