Authentication flow
Enable your users to securely connect their QuickBooks Desktop to your application.
This guide explains how to integrate Conductor’s QuickBooks Desktop authentication flow into your application, enabling your users to securely connect their QuickBooks Desktop to your Conductor account. There are two main approaches:
- Integrate the auth flow with your backend to manage multiple users and connections.
- Generate shareable auth links for getting started quickly or one-off connections.
Integrate the auth flow with your backend
If you are building a multi-user service where each user needs to connect their QuickBooks Desktop account to your application, you’ll want to integrate Conductor’s QuickBooks Desktop authentication flow into your backend.
Create an EndUser
Consider you have an end-user of your application who needs to connect their QuickBooks Desktop to your application. Begin by creating an EndUser for that user and saving their id
to your database. You will use this id
to match your users to their corresponding QuickBooks Desktop connection in Conductor.
If your database has a users
table, consider creating a column called conductor_end_user_id
.
import Conductor from "conductor-node";
const conductor = new Conductor("{{YOUR_SECRET_KEY}}");
// Replace the placeholders with your actual data.
const endUser = await conductor.endUsers.create({
sourceId: "{{UNIQUE_ID_FROM_YOUR_DB}}",
email: "{{END_USER_EMAIL}}",
companyName: "{{END_USER_COMPANY_NAME}}",
});
// Save the EndUser ID to your database.
await db.users.update({
conductorEndUserId: endUser.id,
});
Check if the EndUser has an active QuickBooks Desktop connection
The next step is to initiate an AuthSession for your user to connect their QuickBooks Desktop. However, what if they already has an active connection? Or, what if they previously started the auth flow but didn’t complete it?
Imagine your application has a web app where your users configure the integrations with their application. If you create a section for the QuickBooks Desktop integration, you can use the following approach to track whether an active connection already exists:
try {
// Ping to check the connection status.
await conductor.endUsers.ping("{{END_USER_ID}}", "quickbooks_desktop");
updateUI("QuickBooks Desktop is successfully connected!");
} catch (error) {
if (error instanceof ConductorIntegrationConnectionError) {
if (error.code === "INTEGRATION_CONNECTION_NOT_SET_UP") {
// Initiate an AuthSession if the user never started or completed the auth flow.
const authSession = await conductor.authSessions.create({
publishableKey: "{{YOUR_PUBLISHABLE_KEY}}",
endUserId: "{{END_USER_ID}}",
});
updateUI("Set up your QuickBooks Desktop connection: " + authSession.authFlowUrl);
} else {
// Display connection errors for your user to resolve.
updateUI("An error occurred: " + error.userFacingMessage);
}
} else {
throw error;
}
}
Note: Replace updateUI()
with your actual code that updates your application’s UI based on the status or errors received.
Create a shareable auth flow link
For a quick start, particularly useful for pilot deployments or small-scale operations, generate a secure, shareable link for the QuickBooks Desktop authentication flow:
Create an EndUser
If you haven’t already done so, create an EndUser and save their id
. You will use this id
to authenticate future requests.
Create an AuthSession
Using the EndUser ID, create an AuthSession with an extended link expiry time if needed:
Share the auth flow link
Share the generated authFlowUrl
with your end-user to direct them to the authentication flow to connect their QuickBooks Desktop instance to your application.
The link will resemble this mock example:
https://connect.conductor.is/qbd/auth_sess_client_secret_1234567abcdefg?key={{YOUR_PUBLISHABLE_KEY}}