Autenticazione

Ogni chiamata (tranne l’endpoint token di OAuth) porta un token nell’header:

Authorization: Bearer vn_live_…

Token e client OAuth li crei nel CMS in Impostazioni › Accesso API. Per farlo ti serve il permesso per l’API (vedi Gestire i permessi).

Token API

La strada più semplice per i tuoi script e server: un token appartiene al tuo account, ha permessi fissi e, se vuoi, scade. Nel CMS lo revochi in qualsiasi momento – smette subito di essere valido. Il token viene mostrato una sola volta; conservalo in un gestore di password o di segreti.

Client OAuth: da server a server

Se la tua applicazione deve procurarsi da sola token di breve durata, crei un client OAuth e scambi ID client e segreto con un token:

curl https://cloud.viewneo.com/api/public/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$CLIENT_ID"'",
    "client_secret": "'"$CLIENT_SECRET"'",
    "scope": "media:read playlists:read"
  }'

Un token ottenuto in questo modo vale un’ora. Poi ne ottieni uno nuovo con la stessa chiamata. scope è facoltativo e può solo restringere i permessi del client.

Client OAuth: per conto di un utente

Per le applicazioni che lavorano per conto di una persona del tuo team, mandi l’utente alla pagina di consenso del CMS:

https://cloud.viewneo.com/oauth/authorize?client_id=…&redirect_uri=…&scope=media:read%20playlists:read&state=…

Se l’utente acconsente, il browser torna alla tua redirect_uri con ?code=…. Il codice lo scambi all’endpoint token con grant_type=authorization_code. È utilizzabile una sola volta e vale cinque minuti; la redirect_uri deve corrispondere esattamente a una di quelle registrate per il client.

La risposta contiene inoltre un refresh token, con cui ottieni un nuovo token senza un nuovo consenso (grant_type=refresh_token):

• Ogni refresh fornisce un nuovo refresh token e rende non valido quello vecchio. Salva sempre il più recente.
• Se un vecchio refresh token viene usato di nuovo, viewneo blocca l’intera catena – l’utente deve acconsentire di nuovo.
• Un refresh token vale 90 giorni dall’ultimo utilizzo. Termina anche se il client viene revocato, il plugin API viene disdetto o i permessi dell’utente vengono modificati.

Permessi (scope)

Un token non può mai fare più di quanto consentono i suoi permessi – e mai più di quanto può fare la persona che l’ha creato.

Scope	consente	Permesso nel CMS
media:read	leggere file multimediali e cartelle	File multimediali: Vedi
media:write	caricare, rinominare, spostare, eliminare file multimediali	File multimediali: Gestisci
playlists:read	leggere le playlist	Playlist: Vedi
playlists:write	creare, rinominare, eliminare playlist; modificare le voci	Playlist: Gestisci
devices:read	leggere dispositivi e gruppi	Dispositivi: Vedi
devices:write	attivare e configurare dispositivi, gestire gruppi	Dispositivi: Gestisci
reports:read	prove di riproduzione e report	Dispositivi: Vedi

Uno scope :write include il corrispondente :read. Se manca lo scope necessario, l’API risponde con 403 FORBIDDEN.