Authentication

Every call (except the OAuth token endpoint) carries a token in the header:

Authorization: Bearer vn_live_…

You create tokens and OAuth clients in the CMS under Settings › API access. For this you need the API permission (see Manage permissions).

API token

The simplest way for your own scripts and servers: a token belongs to your account, carries fixed scopes and expires if you want it to. You can revoke it in the CMS at any time – it is then invalid immediately. The token is shown only once; keep it in a password or secret manager.

OAuth client: server to server

If your application should obtain short-lived tokens itself, create an OAuth client and exchange the client ID and secret for a 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"
  }'

A token obtained this way is valid for one hour. After that, you get a new one with the same call. scope is optional and can only restrict the client’s scopes.

OAuth client: on behalf of a user

For applications that work on behalf of a person on your team, send the user to the consent page in the CMS:

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

If the user consents, the browser returns to your redirect_uri with ?code=…. You exchange the code at the token endpoint with grant_type=authorization_code. It can be used once and is valid for five minutes; the redirect_uri must exactly match one of those registered for the client.

The response also contains a refresh token with which you get a new token without new consent (grant_type=refresh_token):

• Every refresh returns a new refresh token and invalidates the old one. Always store the newest one.
• If an old refresh token is used again, viewneo blocks the entire chain – the user has to consent again.
• A refresh token is valid for 90 days from its last use. It also ends if the client is revoked, the API plugin is canceled or the user’s permissions are changed.

Scopes

A token can never do more than its scopes allow – and never more than the person who created it is allowed to do.

Scope	allows	Permission in the CMS
media:read	Read media and folders	View media
media:write	Upload, rename, move, delete media	Manage media
playlists:read	Read playlists	View playlists
playlists:write	Create, rename, delete playlists; change entries	Manage playlists
devices:read	Read devices and groups	View devices
devices:write	Activate and configure devices, manage groups	Manage devices
reports:read	Proof of play and reports	View devices

A :write scope includes the matching :read. If the required scope is missing, the API responds with 403 FORBIDDEN.