Authentifizierung

Jeder Aufruf (außer dem Token-Endpunkt von OAuth) trägt ein Token im Header:

Authorization: Bearer vn_live_…

Tokens und OAuth-Clients legst du im CMS unter Einstellungen › API-Zugang an. Dafür brauchst du das Recht für die API (siehe Rechte verwalten).

API-Token

Der einfachste Weg für eigene Skripte und Server: Ein Token gehört zu deinem Konto, trägt feste Berechtigungen und läuft auf Wunsch ab. Im CMS widerrufst du es jederzeit – es ist dann sofort ungültig. Das Token wird nur einmal angezeigt; bewahre es in einem Passwort- oder Secret-Manager auf.

OAuth-Client: Server zu Server

Soll sich deine Anwendung selbst kurzlebige Tokens holen, legst du einen OAuth-Client an und tauschst Client-ID und Secret gegen ein 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"
  }'

Ein so erhaltenes Token gilt eine Stunde. Danach holst du mit demselben Aufruf ein neues. scope ist optional und kann die Berechtigungen des Clients nur einschränken.

OAuth-Client: im Namen eines Nutzers

Für Anwendungen, die im Namen einer Person aus deinem Team arbeiten, schickst du den Nutzer auf die Zustimmungsseite im CMS:

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

Stimmt der Nutzer zu, kehrt der Browser mit ?code=… zu deiner redirect_uri zurück. Den Code tauschst du mit grant_type=authorization_code am Token-Endpunkt. Er ist einmal verwendbar und fünf Minuten gültig; die redirect_uri muss genau einer der beim Client eingetragenen entsprechen.

Die Antwort enthält zusätzlich ein Refresh-Token, mit dem du ohne neue Zustimmung ein neues Token holst (grant_type=refresh_token):

• Jeder Refresh liefert ein neues Refresh-Token und macht das alte ungültig. Speichere immer das neueste.
• Wird ein altes Refresh-Token noch einmal benutzt, sperrt viewneo die ganze Kette – der Nutzer muss neu zustimmen.
• Ein Refresh-Token gilt 90 Tage ab der letzten Nutzung. Es endet auch, wenn der Client widerrufen, das API-Plugin gekündigt oder die Rechte des Nutzers geändert werden.

Berechtigungen (Scopes)

Ein Token kann nie mehr, als seine Berechtigungen erlauben – und nie mehr, als die Person darf, die es angelegt hat.

Scope	erlaubt	Recht im CMS
media:read	Medien und Ordner lesen	Medien ansehen
media:write	Medien hochladen, umbenennen, verschieben, löschen	Medien verwalten
playlists:read	Playlists lesen	Playlists ansehen
playlists:write	Playlists anlegen, umbenennen, löschen; Einträge ändern	Playlists verwalten
devices:read	Geräte und Gruppen lesen	Geräte ansehen
devices:write	Geräte aktivieren und einstellen, Gruppen verwalten	Geräte verwalten
reports:read	Abspielnachweise und Reports	Geräte ansehen

Ein :write-Scope schließt das passende :read ein. Fehlt der nötige Scope, antwortet die API mit 403 FORBIDDEN.