This article will describe each authentication API and demonstrate how developers can utilize their functionality in a brief code example.

All owner-level API requests in the /rest section of the API documentation require session authentication with a fresh bearer token to enforce password checks before executing API requests. Please review the VMS Server API documentation for more information on how to properly utilize parameters and execute the API requests.

HTTP Bearer/Session Token Authentication

Nx Witness 5.0 introduced HTTP Bearer/Session Token Authentication, an improved authentication method recommended over the deprecated methods from prior versions of Nx Witness.

A bearer token is a cryptic string generated by Nx Witness Server in response to a login request. An Nx Witness client must send this token in the authorization header when making requests to protected resources. This method can only be used over HTTPS or RTSPS. Raw HTTP or RTSP requests cannot be made. 

Local and LDAP Users

The following steps demonstrate how to authenticate API requests for Local and LDAP users:

1. [Optional] Check user type on the VMS Server to confirm they are not a Cloud user.
2. Execute a login request to the VMS Server to obtain two bearer tokens: one to initiate the API call and another to delete the first. For cookie-based authentication, setCookie should be set to true. Afterward, all web browser requests to the VMS Server will be authorized automatically.
3. [Optional] Check if the bearer token is valid on the VMS Server.
4. Execute any request which requires authentication with a bearer token on the VMS Server.
   Note: Requests involving Video Walls require the Video Wall ID in the request. See the API documentation for more details.
5. Terminate a session that is no longer needed on the VMS Server.

You can also find this example in the Nx GitHub repository.

Cloud Users

The following steps demonstrate how to authenticate API requests for Cloud users:

1. Check if the system is connected to the Cloud and get its Cloud System ID from the VMS Server. If the Cloud System ID is not listed, the system is not connected to the Cloud and does not have any Cloud users.
2. [Optional] Check the user type on the VMS Server. Only Cloud users may use Cloud Sessions.
   Note: Field methods will not contain sessions because the VMS Server does not give sessions for Cloud users.
3. Cloud users must obtain two bearer tokens from the Cloud: one to initiate the API calls and another to delete the first token when finished.
4. [Optional] Check if the session token is valid on the VMS Server. For cookie-based authentication, add the ?setCookie=true URL parameter. Afterward, all web browser requests to the VMS Server will be authorized automatically.
5. Execute any request which requires authentication with a bearer token on the VMS Server.
6. Cloud sessions can be terminated on the Cloud when it's no longer needed.

You can also find this example in the Nx GitHub repository.

Deprecated Authentication in Nx Witness

While examples for Digest Authentication are included in the Nx Github Repository, this method has been deprecated since version 5.0 and is kept solely for legacy support. It will be removed in a future release, so we strongly recommend using only the supported authentication methods.