Overview

This article will go over the steps for integrating with the Nx Witness OAuth API. Integrations that use the Cloud API to fetch data from a user's Nx Witness Cloud System will only be able to do so after a user is authenticated. Any developer with JavaScript experience (especially with using Fetch API or similar third-party alternatives) should have the necessary skills to use the Nx Witness OAuth API.

There are several benefits to using OAuth over the much less secure Basic Authentication which exposes the user and password:

• More secure as your password is never exposed after you get the access codes (it is similar to how Social Auth works).
• Two-factor authentication (2FA) is supported.
• Authorize other apps to use the Cloud API for you.

Prerequisites:

• Preferred local webhost tool (our examples use the one built into Python 3.x)
• Your preferred JavaScript editor
• Online Nx Witness System connected to Nx Cloud

How to write code and test the integration:

1. Create a folder.
2. Create an empty index.html file in the folder.
3. Open the oauth_demo.html file in your preferred JavaScript editor and write your code.
4. Host the oauth_demo.html file on a local web server for testing purposes.
      a. Open CMD/terminal and navigate to the folder created in step 2. 
      a. Run the command: python3 -m http.server 7002
5. Open oauth_demo.html page in a browser (https://localhost:7002/oauth_demo.html)

We wrote an example using our API to demonstrate the following functionality useful for creating a web app:

1. Your web app must redirect the user to the Nx Witness Cloud authorization page.
   Example: https://nxvms.com/authorize?redirect_url=https://{your app}
2. Then that page will return a code in the query parameters of the redirect URL.
   Example: https://nxvms.com?code={some code}
3. The code should be used in the following way to get access and refresh codes
      a. Insert request for tokens.
4. Refresh code can be used to obtain an access code or a new refresh token
      a. Read about scope in the How scope works section.
      b. Insert request for new code or tokens.

The full example can be found in the GitHub Open Integrations repository.