Intuit OAuth Node.js Client

Methods that perform authentication (like createToken or refresh) return an AuthResponse object. This is a wrapper containing the raw HTTP response and the parsed token data.

Key properties and methods:

• token: An instance of the Token object.
• json: The parsed JSON body from the response.
• response: The raw HTTP response object.
• intuit_tid: The intuit-tid from the response headers.
• status(): Returns the HTTP status code.
• text(): Returns the response body as text.
• get_intuit_tid(): Helper to retrieve the Intuit Transaction ID.

oauthClient.createToken(parseRedirect).then(function (authResponse) {
  console.log('The Token in JSON is  ' + JSON.stringify(authResponse.json));
  let status = authResponse.status();
  let body = authResponse.text();
  let jsonResponse = authResponse.json;
  let intuit_tid = authResponse.get_intuit_tid();
});

The makeApiCall method supports both absolute and relative URLs:

• Absolute URL: Provides the full endpoint (e.g., https://sandbox-quickbooks.api.intuit.com/v3/company/123/item).
• Relative URL: Provides the path starting from the root (e.g., /v3/company/123/item). The client automatically prepends the correct base URL based on your configured environment.

Access tokens expire after 1 hour (3600 seconds). Use isAccessTokenValid() to check the current token's status and refresh() to obtain a new one if it has expired.

if (!oauthClient.isAccessTokenValid()) {
  await oauthClient.refresh();
}

To use the library, require intuit-oauth and instantiate a new OAuthClient with your application credentials.

Required Options:

• clientId: Your application's client ID.
• clientSecret: Your application's client secret.
• environment: Either 'sandbox' or 'production'.
• redirectUri: The callback URL on your application. This must match the redirect URI configured in your Intuit Developer Portal under the Keys & OAuth tab.

Optional Options:

• logging: Set to true to enable logging (defaults to false).

const OAuthClient = require('intuit-oauth');

const oauthClient = new OAuthClient({
  clientId: '<Enter your clientId>',
  clientSecret: '<Enter your clientSecret>',
  environment: 'sandbox' || 'production',
  redirectUri: '<Enter your callback URL>',
});

Access tokens are valid for 3600 seconds (one hour). You can use isAccessTokenValid() to check if the current token is expired. If it is invalid, use the refresh() method to obtain a new access token using the most recent refresh_token.

Note: Always use the refresh_token returned in the most recent token_endpoint response. Previous refresh tokens expire 24 hours after a new one is issued.

if (oauthClient.isAccessTokenValid()) {
  console.log('The access_token is valid');
} else {
  oauthClient
    .refresh()
    .then(function (authResponse) {
      console.log('Tokens refreshed : ' + JSON.stringify(authResponse.getToken()));
    })
    .catch(function (e) {
      console.error('The error message is :' + e.originalMessage);
      console.error(e.intuit_tid);
    });
}

Install the intuit-oauth package via npm to use the Intuit OAuth2.0 NodeJS library.

npm install intuit-oauth --save

The createToken() method always throws errors on failure rather than returning them. When an error occurs, catch the exception to access specific OAuth2 error details such as error (e.g., invalid_grant), error_description, and intuit_tid (Transaction ID) for support.

try {
  const authResponse = await oauthClient.createToken(code);
  const token = authResponse.getToken(); // Access token data on success
} catch (error) {
  console.log('Error:', error.error); // e.g., "invalid_grant"
  console.log('Description:', error.error_description); // e.g., "Token invalid"
  console.log('Transaction ID:', error.intuit_tid); // For support
  
  if (error.error === 'invalid_grant') {
    // Handle specific error, e.g., redirect user to re-authorize
  }
}

Edit the .env file in the sample directory to configure the application behavior. Key variables include:

• PORT: (Optional) The port number on which the application will be served.
• NGROK_ENABLED: (Optional) Set to true if you want to serve the app over HTTPS via ngrok. This is mandatory if you are testing with Production Credentials. Defaults to false.

If NGROK_ENABLED is set to true, the application will attempt to use ngrok to expose your local endpoint to the internet automatically.

To enable logging for debugging purposes, pass logging: true in the configuration object when instantiating the OAuthClient. Logs are written to /logs/oAuthClient-log.log.

const oauthClient = new OAuthClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  environment: 'sandbox',
  redirectUri: 'http://localhost:8000/callback',
  logging: true // Enable logging
});

To use the Intuit OAuth 2.0 client in your Node.js project, install the intuit-oauth package using npm.

npm install intuit-oauth