Bring your own Intuit app

Before you start

These steps come after two things are settled with Compass, not before.

1. You have contacted Compass and confirmed that the multi-tenant platform has been updated for your white-label needs: your product name, branding, sender addresses and tenant configuration are in place.
2. Compass has set up the white-label web origin for your app, both in Compass and on your side. The origin is the address your customers open, such as https://app.yourproduct.com, and it needs DNS on your domain pointing at Compass. The redirect URIs below depend on it, so do not create the Intuit app until it exists.

You also need an Intuit developer account owned by your organisation, not by an individual, since the app, its assessment and its production keys stay with that account.

Create the app

1. Sign in at developer.intuit.com and create a new app for QuickBooks Online. Name it after your product, since that name is what your customers see on the consent screen.
2. Select only the com.intuit.quickbooks.accounting scope. Compass reads accounting data and nothing else; it never asks for payments, payroll or OpenID scopes.
3. Intuit issues a development client ID and secret at once. Production keys come later, after the assessment below.

Redirect and app URLs

Compass completes the connection on the /dashboard route of your web origin, so every redirect URI is that origin plus /dashboard, one per environment.

1. Production: https://app.yourproduct.com/dashboard, using the origin from the step above.
2. Sandbox: the development origin Compass gives you plus /dashboard. Compass runs a shared development environment for the sandbox acceptance test.
3. Host domain, launch URL and disconnect URL: your origin, with /dashboard/integrations as the launch and disconnect page. That is where your customers connect, sync and disconnect QuickBooks.

Register the URIs exactly as written. Intuit compares them byte for byte, and production keys only accept HTTPS.

Production settings and the assessment

Intuit requires an app assessment questionnaire before it releases production keys, for private apps as well as listed ones. Most of it is about your organisation; the technical answers come from Compass.

1. Hosting country and IP addresses: ask Compass for the details of your tenant region. Compass runs in AWS, in the United States or the European Union depending on where your customers are.
2. When the questionnaire asks which of the following is true about your app, select You were asked to create this app in order to get credentials/keys to be used on another platform that integrates with QuickBooks and give this page as the link to the instructions.
3. Compass supplies the answers on OAuth behaviour, token handling, error handling, data use and security on request, and can join the call while you fill the questionnaire in.

Hand over the keys

1. Never send a client ID and secret by email or chat. Use a recipient-restricted, single-view secret link, such as a shared vault item, or a channel Compass agrees with you.
2. Send the development pair first. Compass installs it for your tenant, confirms, and runs the sandbox acceptance test with you: connect, import, manual sync, disconnect, reconnect.
3. Send the production pair only after Intuit approval and before the agreed cut-over. Compass keeps each pair in its secret store, scoped to your tenant, and uses it for your customers only.

Switching an existing tenant

If your customers already connected QuickBooks through the Compass app, their tokens are bound to that app. Once Compass switches your tenant to your keys, every existing connection stops refreshing and each customer reconnects once from the Integrations page. Plan a communicated reconnect window with Compass rather than a silent switch, and keep the previous keys available until the first reconnects have synced.