Implementazione server-side di una vetrina di asset su sito, portale o applicazione: autenticazione JWT, recupero contenuti, filtri e distribuzione dei file.

Cosa ti serve prima di iniziare

Assicurati di avere tutte le credenziali prima di iniziare. Alcune le fornisce il team THRON, altre le ottieni dal Content Manager che gestisce la piattaforma.

Come richiedere l'utente al Content Manager

Per accedere ai contenuti di una cartella via API, THRON verifica che l'utente con cui operi abbia i diritti su quella cartella. Non puoi usare solo le credenziali dell'app: hai bisogno di un utente THRON reale da impersonificare nelle chiamate, tramite il meccanismo di User Impersonation.

Chiedi al Content Manager di:

1. Creare un utente THRON dedicato all'integrazione (es. api-website o integration-[nome-progetto])

2. Assegnargli diritti di lettura sulla cartella che vuoi esporre

3. Comunicarti lo username, non ti serve la password

## Articoli di approfondimento
- 
Configurare Gruppi e Utenti, guida per il Content Manager su come creare l'utente e assegnare i diritti sulla cartella

Autenticazione

THRON usa OAuth 2.0 con token JWT. Per accedere a contenuti e cartelle, che verificano i permessi di accesso tramite ACL, è necessaria la User Impersonation: il sistema si autentica con le credenziali dell'app ma opera con i diritti dell'utente dedicato che ha accesso alla cartella.

Flusso consigliato: User Impersonation

Usa questo flusso ogni volta che devi accedere a contenuti o cartelle specifici.

POST /api/v1/authentication/oauth2/token HTTP/1.1
Host: {tenantId}.thron.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:thron:oauth:user-impersonation
&scope=
&client_id={client_id}
&client_secret={client_secret}
&subject={username}

In risposta ricevi access_token (JWT) e refresh_token. Il token dura 8 ore (expires_in: 28800).

Flusso alternativo: Client Credentials

Usa questo flusso solo per operazioni che non richiedono accesso a contenuti o cartelle specifici. Senza User Impersonation il token non ha ACL sulle cartelle e non restituisce contenuti.

POST /api/v1/authentication/oauth2/token HTTP/1.1
Host: {tenantId}.thron.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=
&client_id={client_id}
&client_secret={client_secret}

Rinnova il token

Quando l'access token scade (risposta 403 Session Expired) usa il refresh token per ottenerne uno nuovo senza ripetere l'autenticazione completa.

POST /api/v1/authentication/oauth2/token HTTP/1.1
Host: {tenantId}.thron.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}

In risposta ricevi un nuovo access_token e un nuovo refresh_token. Quello precedente non è più valido.

## Articoli di approfondimento
- 
Documentazione API THRON, sezione "Authentication" per il riferimento completo agli endpoint

JWT e XTokenID: quando usare quale

Le nuove API THRON usano il JWT nell'header Authorization:

Authorization: Bearer {access_token}

Alcune API legacy richiedono ancora il token XTokenID nell'header X-TokenID. Per ottenerlo dal JWT:

GET /api/v1/authentication/token/legacy HTTP/1.1
Host: {tenantId}.thron.com
Authorization: Bearer {access_token}

Risposta:

{ "token": "e1aff403-6583-40f1-961c-f91458aa2112" }

Usa il valore restituito aggiungendo l'header X-TokenID: {token} alle chiamate che lo richiedono.

## Articoli di approfondimento
- 
Documentazione API THRON, ogni endpoint indica il tipo di token supportato

Ricerca asset e filtri

Per recuperare gli asset della cartella usa le API di ricerca documentate nel portale ufficiale. Le chiamate vanno eseguite con il token ottenuto tramite User Impersonation: solo così il sistema restituisce i contenuti a cui l'utente impersonificato ha accesso.

Se è configurato un attributo filtro in piattaforma (select o multiselect), il flusso tipico è:

1. Recupera i valori disponibili dell'attributo, poi usali per costruire i filtri nell'interfaccia

2. Esegui la ricerca degli asset applicando il valore selezionato dall'utente

## Articoli di approfondimento
- 
Documentazione API THRON, sezione "Content Search" per parametri, filtri e paginazione

Distribuzione dell'asset sul canale

Hai due modi per mostrare un asset sul canale esterno: comporre l'URL di delivery e gestire tu il markup, oppure delegare la resa al Player THRON.

Delivery dell'asset tramite API

Ogni asset è raggiungibile tramite un URL di delivery servito dalla CDN THRON. Inseriscilo dove ti serve nel markup: in un tag img, nel player nativo del browser, in un player di terze parti o in un link di download.

Usa questo metodo quando hai pieno controllo sull'interfaccia e vuoi decidere tu come il contenuto viene renderizzato.

https://{clientId}-cdn.thron.com/api/v1/content-delivery/shares/{pKey}/contents/{contentId}/image/{dynamicSeoSuffix}?w=800&crop=auto

I segmenti dell'URL:

Sulle immagini puoi aggiungere parametri di query per ottenere al volo la resa che ti serve, senza generare varianti in piattaforma: dimensioni (w, h), modalità di ritaglio (crop), qualità (q) e durata della cache del browser (maxAge).

## Articoli di approfondimento
- 
Come funziona il Real Time Image Editor su AMBRA AI MEDIABOOST, elenco completo dei parametri di manipolazione delle immagini
- 
Embeddare un Digital Asset in un sito o pagina web esterna, come ottenere URL e pKey dalla piattaforma
- 
Documentazione API THRON, sezione "Content Delivery" per le rotte disponibili per ogni tipo di asset

Player THRON

In alternativa delega la resa al Player THRON, che gestisce automaticamente formati, responsive, accessibilità, controlli di riproduzione e la Content Experience configurata in piattaforma. Il codice di embed lo genera la piattaforma: non devi scriverlo a mano.

Usa questo metodo quando vuoi la stessa esperienza di riproduzione già in uso sugli altri canali, o quando distribuisci video e non vuoi gestire tu adattamento della qualità e controlli.

## Articoli di approfondimento
- 
Embeddare un Digital Asset in un sito o pagina web esterna, come generare e personalizzare il codice di embed
- 
THRON Player: nuova versione, versioni template e compatibilità CEM

Configurazione consigliata

Serve aiuto?

Per problemi tecnici, scrivi a support@thron.com.