Is the Nx Cloud up? Visit our Status Page for the current health and performance of the Nx Cloud.

Status Page

Cloud Authentication overview

Nx Support
Updated
Integrations making API requests to read or write data on a Cloud Connected Site must authenticate first. The recommended authentication method is OAuth 2.0 using the Cloud DB API.
 
Your integration exchanges the user's Cloud credentials for a session token, then uses that token as a Bearer token on all subsequent requests.
 

Understanding OAuth 2.0

OAuth 2.0 is an authorization protocol that lets third-party applications access user data on a service without exposing the user's password.
 
The protocol defines four main roles:
  • Resource Owner: The user who owns the data and grants access to it.
  • Client: The application or service requesting access to the user's data.
  • Authorization Server: The server that authenticates the user and issues access tokens. In the VMS, this is the Cloud DB server.
  • Resource Server: The server hosting the protected resources. In the VMS, this is the Site or Media Server.

Why use OAuth 2.0?

Older integration methods often required applications to store and transmit actual usernames and passwords, creating security risks. OAuth 2.0 solves this issue by storing credentials securely on the central service and issuing revocable, limited-scope permissions to third-party apps
 
OAuth 2.0 offers several security advantages:
  • Reduces credentials in transit: Basic authentication sends the username and password with every request. OAuth 2.0 authenticates once to issue a token, limiting exposure if traffic is intercepted.
  • Supports two-factor authentication (2FA): Because authentication occurs through the Cloud DB, any 2FA settings enabled on the user account are enforced automatically.
  • Provides scoped and revocable access: You can tie a session token to a specific system and revoke it at any time without changing the user's password.
  • Enforces extra checks for administrative actions: API requests requiring admin permissions require the token to be re-confirmed with the administrator password.

How the Cloud OAuth flow works

Because Cloud user accounts reside in the Cloud rather than on local VMS Media Servers, your integration must request tokens directly from the Cloud DB endpoint.
 
To authenticate a user and perform API requests, complete the following steps:
  1. Request tokens: Send a POST request containing the user's email, password, requested site scope, and 2FA code (if enabled) to the Cloud DB token endpoint:
    POST /cdb/oauth2/token
  2. Receive tokens: Upon validation, the Cloud DB returns an access token (prefixed with nxcdb-), its expiration time, and a refresh token.
  3. Authenticate API requests: Pass the access token in the HTTPS Authorization header on every subsequent request:
    Authorization: Bearer <token>
    NOTE: Web clients can also request the token as a cookie so the browser handles authentication automatically.
  4. Refresh expired tokens: When the access token expires, send the refresh token to the token endpoint to obtain a new access token without requiring the user to sign in again.

Local site authentication

Cloud authentication applies only to sites connected to the Cloud. If your site is not connected to the Cloud:
  1. Authenticate directly against the local Media Server using a local user account.
  2. Obtain a local Bearer session token directly from the local server.
For detailed steps on local authentication, refer to the Login section in the API documentation.
 

Next steps

  • Review complete OAuth 2.0 request and response specifications in the Authentication section of the API documentation and the Cloud DB API reference.
  • Download and test functional code samples from the Nx Open GitHub API Sample repository.

Related articles

Comments

0 comments

Article is closed for comments.