Authentification

Chaque appel (sauf l’endpoint de jeton d’OAuth) porte un jeton dans l’en-tête :

Authorization: Bearer vn_live_…

Tu crées les jetons et les clients OAuth dans le CMS, sous Paramètres › Accès API. Il te faut pour cela l’autorisation pour l’API (voir Gérer les autorisations).

Jeton d’API

La solution la plus simple pour tes propres scripts et serveurs : un jeton appartient à ton compte, possède des autorisations fixes et expire si tu le souhaites. Dans le CMS, tu le révoques à tout moment – il devient alors immédiatement invalide. Le jeton n’est affiché qu’une seule fois ; conserve-le dans un gestionnaire de mots de passe ou de secrets.

Client OAuth : serveur à serveur

Si ton application doit obtenir elle-même des jetons de courte durée, crée un Client OAuth et échange l’identifiant client et le secret contre un jeton :

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 jeton obtenu ainsi est valable une heure. Ensuite, tu en obtiens un nouveau avec le même appel. scope est facultatif et ne peut que restreindre les autorisations du client.

Client OAuth : au nom d’un utilisateur

Pour les applications qui agissent au nom d’une personne de ton équipe, tu envoies l’utilisateur vers la page de consentement du CMS :

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

Si l’utilisateur donne son accord, le navigateur revient vers ta redirect_uri avec ?code=…. Tu échanges ce code à l’endpoint de jeton avec grant_type=authorization_code. Il est utilisable une seule fois et valable cinq minutes ; la redirect_uri doit correspondre exactement à l’une de celles enregistrées pour le client.

La réponse contient en plus un jeton d’actualisation, avec lequel tu obtiens un nouveau jeton sans nouveau consentement (grant_type=refresh_token) :

• Chaque actualisation fournit un nouveau jeton d’actualisation et rend l’ancien invalide. Enregistre toujours le plus récent.
• Si un ancien jeton d’actualisation est réutilisé, viewneo bloque toute la chaîne – l’utilisateur doit donner à nouveau son consentement.
• Un jeton d’actualisation est valable 90 jours à compter de sa dernière utilisation. Il prend aussi fin si le client est révoqué, si le plug-in API est résilié ou si les autorisations de l’utilisateur sont modifiées.

Autorisations (scopes)

Un jeton ne peut jamais faire plus que ce que ses autorisations permettent – ni plus que ce que la personne qui l’a créé a le droit de faire.

Scope	permet	Autorisation dans le CMS
media:read	lire les médias et les dossiers	Médias : Consulter
media:write	téléverser, renommer, déplacer, supprimer des médias	Médias : Gérer
playlists:read	lire les playlists	Playlists : Consulter
playlists:write	créer, renommer, supprimer des playlists ; modifier des éléments	Playlists : Gérer
devices:read	lire les appareils et les groupes	Appareils : Consulter
devices:write	activer et configurer des appareils, gérer des groupes	Appareils : Gérer
reports:read	preuves de diffusion et rapports	Appareils : Consulter

Un scope :write inclut le :read correspondant. S’il manque le scope nécessaire, l’API répond 403 FORBIDDEN.