Authorizing a Web Application

This article will cover how to integrate Nx Witness Cloud OAuth API into your web app. To integrate a service, you will utilize the Authorization URL https://nxvms.com/authorize in addition to using the Access Token Requests and Refresh Token Requests described on the prior page. The Authorization URL allows the service to use the Nx Cloud authorization page.

Putting It All Together

1. Let's begin by defining the following variables that will be used throughout the code:

   let tokens, access_token, refresh_token;
   const url = new URL(window.location.href);
   const cloudHost = 'https://nxvms.com';

2. Afterward, build a URL for opening the Nx Witness Cloud Oauth. The client_id should be something unique to your app (such as your app name). state is only needed if your app wants to keep something or verify the redirect.

   const buildOauthUrl = () => {
   const redirectUrl = new URL(cloudHost/authorize);
   redirectUrl.searchParams.set('redirect_url', window.location.href);
   redirectUrl.searchParams.set('client_id', '{something unique to your app}');
   redirectUrl.searchParams.set('state', '{something}') 
   return redirectUrl.toString();
   };

3. Redirect your webpage using the URL from step 1.

   const redirectOauthLogin = (cloudAuthUrl) => {
   window.location.href = cloudAuthUrl;
   };

4. After the user has finished logging in by using the Cloud Authorize dialog the browser will be redirected back to your redirect_url. After this happens, there will be a code in the query parameters in the URL. Extract it and use it as your authorization code to generate access_tokens for API requests:

   const url = new URL(window.location.href);
   const code = url.searchParams.get('code');

5. You can optionally clean up the URL afterward to remove the extra query parameters that were added in the prior steps.

   const cleanupCode = () => {
   url.searchParams.delete('code');
   window.history.pushState({}, undefined, url.toString());
   };

6. Make a POST API request to Nx Cloud with the code from step 3. 

   const postWrapper = (url, data) => {
   const options = {
   method: "POST",
   body: JSON.stringify(data)
   };
   return fetch(url, options).then(r => r.json());
   };
   
   const getTokensWithCode(code) => {
   const data = {
   code,
   grant_type: 'authorization_code',
   response_type: 'token'
   };
   return postWrapper(`${cloudHost}/oauth/tokens/`, data);
   };
   
   getTokensWithCode(code);

7. Make a request to Nx Witness Cloud with your access token. In this example, we perform a GET request for a list of the user's systems.

   const getWrapper = (url, params) => {
   const requestUrl = new URL(url);
   requestUrl.search = new URLSearchParams(params).toString();
   const options = {
   method: "GET",
   headers: {},
   };
   if (access_token) {
   options.headers['Authorization'] = `Bearer ${access_token}`
   }
   return fetch(requestUrl.toString(), options).then(r => r.json());
   };
   
   const systems = getWrapper(`${cloudHost}/api/systems`);

The End Result

The full example using the functions from the steps above can be found in the GitHub Open Integrations repository. The code can only be used once so there is no point in saving it. Also, remember to invalidate the tokens when you are done. The end result will vary, but the quick integration example from the repository looks like this: