Connect QuickBooks Online#

Reportworq connects to QuickBooks Online through a CData driver, which presents the QuickBooks company as a relational, tabular source you query with the same table or SQL modes as any database. In the connector catalog the tile is QuickBooks Online. Authentication is OAuth 2.0 against Intuit.

This page covers the part of the setup that is different on a server or headless install: completing the OAuth sign-in when there is no web browser on the Reportworq server itself. For the shared CData add-and-test flow, see Connect CData sources.

A CData driver's default OAuth flow is a desktop flow: it opens a local loopback listener and launches a browser on the machine running the driver. On a server that has no desktop browser, that flow cannot complete.

Reportworq instead uses the server (web) OAuth flow, so no browser is needed on the server:

You reach Reportworq in a browser on your own workstation, as you normally do.
When you select Authenticate, Reportworq builds the Intuit sign-in URL and opens it in a new tab of your browser.
You sign in to QuickBooks and authorize the app. Intuit redirects back to a redirect endpoint on the Reportworq server, and the server exchanges the authorization code for the access and refresh tokens and stores them, encrypted, on the connection.

Because the sign-in happens in your workstation browser and the token exchange happens on the server, the whole flow works on a headless install.

Before you begin#

You are an administrator. Only administrators can add or configure datasource connections.
Reportworq is reachable over HTTPS. OAuth sign-in cannot complete over plain http:// on a non-localhost address, and Reportworq stops with a message saying so. On a server install this means the address you use to reach Reportworq must be https://....
You have an Intuit Developer account and an app (a QuickBooks Online app) with OAuth 2.0 enabled. If you do not, create them first, following Intuit's own developer documentation, then complete the app setup below.

Set up your Intuit app#

You gather three things from Intuit before you configure Reportworq: the OAuth Client Id and OAuth Client Secret, the Redirect URI, and your QuickBooks Company Id.

Copy the Client Id and Client Secret#

In the Intuit Developer portal, open your app and go to Keys & Credentials. On the Production tab, turn on Show credentials to reveal the Client ID and Client secret, and copy both. You enter them into Reportworq as the OAuth Client Id and OAuth Client Secret.

The Intuit Keys and Credentials screen, with the Client ID and Client secret fields hidden behind a Show credentials toggleTap or click the image to view it full screen

Treat the client secret like a password. Do not paste it into email, chat, or a screenshot: notice that the screen above keeps it hidden until you ask to see it.

Register the redirect URI#

In the same app, go to Settings > Redirect URIs and add this exact Redirect URI, replacing the host with your Reportworq address:

https://<your-reportworq-host>/server/v0/oauth-redirect

The Intuit Redirect URIs screen with the Reportworq server redirect URI entered, ending in /server/v0/oauth-redirectTap or click the image to view it full screen

The redirect URI must match exactly between the sign-in request and the token exchange, so register the same value you reach Reportworq at. A mismatch is the most common cause of a failed sign-in. Intuit also requires a real host name here: an IP address is not accepted.

Find your Company Id#

On current builds, Reportworq captures the company automatically when you Authenticate (see below), so you do not normally need to look this up. You still need it if you are on an older build, or if you want to set or override the Company Id by hand. To find it, sign in to QuickBooks Online and open Settings > Subscription and Billing; your Company ID is shown there.

The QuickBooks Online Company ID shown on the Subscription and Billing screen, with the identifier redactedTap or click the image to view it full screen

Add the connection in Reportworq#

Sign in to Reportworq as an administrator and go to Settings > Integrations.

The Reportworq Settings screen showing the Configuration, Security, and Integrations tilesTap or click the image to view it full screen
On the DATASOURCES tab, select Add, find QuickBooks Online in the catalog, and add it. The connection editor opens.
Select Enable datasource connection and give the connection a Datasource Name (for example, QuickBooks). This is the name your formulas refer to, so it must be unique across the instance and is awkward to change later. Select Show Advanced Options to reveal the full OAuth settings.

The QuickBooks datasource settings in Reportworq: Enable datasource connection selected, a Datasource Name of QuickBooks, and Show Advanced Options selectedTap or click the image to view it full screen
In the OAuth section, set Initiate OAuth to GETANDREFRESH, then enter your OAuth Client Id and OAuth Client Secret from Keys & Credentials. On current builds you can leave Company Id empty: it is captured automatically when you Authenticate in step 6. Enter it only if you are on an older build, or want to target a specific company (find it in QuickBooks Subscription and Billing).

The Reportworq OAuth section with Initiate OAuth set to GETANDREFRESH and masked OAuth Client Id, OAuth Client Secret, and Company Id valuesTap or click the image to view it full screen
Save your changes. Selecting Authenticate with unsaved edits returns "Please save changes before performing this operation." The same applies to Sign out.
Select Authenticate. A new browser tab opens with the Intuit / QuickBooks sign-in. Sign in to QuickBooks and authorize the app. When it completes, the tab shows "Authentication complete. You can return to the application. Feel free to close this browser tab." Close the tab and return to Reportworq.
Back in the OAuth section, the read-only fields populate: OAuth Access Token, OAuth Refresh Token, OAuth Settings Location, and OAuth Expires In (for example, 3600). These confirm the sign-in succeeded. You do not edit them by hand.

The Reportworq OAuth advanced fields after authenticating: masked OAuth Access Token and OAuth Refresh Token, the OAuth Settings Location path, and OAuth Expires In showing 3600Tap or click the image to view it full screen
Select Test connection, then Save.

To disconnect, select Sign out, which clears the stored tokens from the connection. (Save any other edits first.)

Query the company#

Once the connection tests, a model author builds views over it on a data model's Connection tab, choosing a Query type of Table or View or SQL Query, exactly as for the other CData and relational sources. See Connect SQL Server, OLE DB, and ODBC and Data models.

Behavior and limits#

No browser is needed on the server. Sign-in runs in your workstation browser; the token exchange runs on the Reportworq server.
Tokens are stored encrypted on the connection, and refreshed automatically at run time. If the connection later stops authenticating, run Authenticate again to sign in fresh.
Reportworq must be reached over HTTPS for sign-in to complete (or localhost in a local dev setup).
The company is captured automatically from the authorization when you Authenticate, and stored as the connection's Company Id. To target a specific company, or on a build that does not capture it, set the Company Id field by hand (found in QuickBooks Settings > Subscription and Billing) and re-authenticate.
Only administrators can add or configure the connection, and editing, disabling, or deleting a live datasource breaks every job and form that refreshes from it.

Troubleshooting#

Symptom	Likely cause	What to do
Please save changes before performing this operation	You selected Authenticate or Sign out with unsaved edits	Save the connection, then try again.
Sign-in will not start, or fails to return	Reportworq is reached over plain `http://` on a non-localhost host	Reach Reportworq over HTTPS, then select Authenticate again.
Intuit rejects the sign-in with a redirect URI error	The redirect URI registered in the Intuit app does not match the address you reach Reportworq at	Register `https://<your-reportworq-host>/server/v0/oauth-redirect` in the Intuit app, matching your Reportworq address exactly.
Sign-in completes but queries return no company data	The company was not captured, or the Company Id is wrong on the connection	Re-run Authenticate to re-capture the company. If it is still wrong, copy your Company Id from QuickBooks Settings > Subscription and Billing, enter it as Company Id, save, and re-authenticate.
A CData or loopback socket error appears during sign-in on the server	The connection is attempting the desktop OAuth flow rather than the server flow	Confirm you are on a build with server-side QuickBooks OAuth, and complete sign-in from your workstation browser against the HTTPS address, not from a browser on the server.

Connect CData sources for the shared CData add-and-test flow and how to find a driver's connection properties.
Connector catalog for the full connector list and the per-connector traps.
Connect a data source for the general add, test, and manage flow.
Data models for turning the connection into curated, reusable data for report authors.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.