Connect an end user

View as Markdown

Your customer connects QuickBooks Desktop by following a setup link that you create. The link opens our hosted setup flow at connect.desktopaccountingapi.com. It guides the person at the QuickBooks computer through installing the connector and checks the connection live before it lets them finish.

The integration pattern

Most products wire it up like this:

When a customer turns on your QuickBooks integration, create an end user (POST /v1/end-users) and save its ID.
Before a sync, or when the customer opens your integration settings, call the health check.
If the health check fails with INTEGRATION_CONNECTION_NOT_SET_UP, create an auth session and show its authFlowUrl with a “Connect QuickBooks Desktop” button.
For any other error, show userFacingMessage to the customer and keep the setup link as a fallback (“Set up the connection again”).
When the customer returns to your redirectUrl with status=completed, run the health check again and start the first sync.

Create a setup link

import { DesktopAccountingApi } from "@desktopaccountingapi/quickbooks-desktop";

const client = new DesktopAccountingApi();

const session = await client.authSessions.create({
  publishableKey: process.env.DAAPI_PUBLISHABLE_KEY ?? "",
  endUserId: "eu_01j9...",
  linkExpiryMins: 1440, // one day
  redirectUrl: "https://app.example.com/settings/quickbooks/done",
});
// Send the customer to session.authFlowUrl

import os
from desktopaccountingapi import DesktopAccountingApi

client = DesktopAccountingApi()

session = client.auth_sessions.create(
    publishable_key=os.environ["DAAPI_PUBLISHABLE_KEY"],
    end_user_id="eu_01j9...",
    link_expiry_mins=1440,  # one day
    redirect_url="https://app.example.com/settings/quickbooks/done",
)
# Send the customer to session.auth_flow_url

curl https://api.desktopaccountingapi.com/v1/auth-sessions \
  -H "Authorization: Bearer $DAAPI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publishableKey": "pk_live_...",
    "endUserId": "eu_01j9...",
    "linkExpiryMins": 1440,
    "redirectUrl": "https://app.example.com/settings/quickbooks/done"
  }'

Field	Rules
`publishableKey`	Required. Your project’s publishable key.
`endUserId`	Required. The end user who connects.
`linkExpiryMins`	15 to 10080 (7 days). Default 30. Use a short expiry when the customer is in front of you, and a few days for a link you email.
`redirectUrl`	Optional absolute `https` URL. Test projects may also use `http://localhost`. Without it, the last page offers a Finish button and the customer closes the tab.

The response contains authFlowUrl, expiresAt and clientSecret. The URL includes the client secret, so treat the link as a credential: send it only to the customer, never log it, and create a fresh one each time you show it. The setup flow swaps the secret for a cookie on first load and then moves to clean URLs, so the secret does not stay in the browser’s history.

The dashboard creates the same links: open an end user and click Create setup link. It offers 30 minutes, 1 day or 7 days.

Show the link

Pick the delivery that fits your product.

Open it on the QuickBooks computer. If your customer uses your web app on the same Windows computer that runs QuickBooks, a button that opens authFlowUrl in a new tab is all you need.
Send it. Many customers use your product on a laptop while QuickBooks runs on an office PC or server. Show the link with a copy button, or email it, and tell them to open it on the QuickBooks computer. Use a longer linkExpiryMins.
Embed it. The flow can run inside an iframe on your page:

<iframe
  src="https://connect.desktopaccountingapi.com/setup/authsess_secret_..."
  title="Connect QuickBooks Desktop"
  sandbox="allow-scripts allow-same-origin allow-downloads allow-popups allow-top-navigation-by-user-activation"
  style="width: 100%; height: 720px; border: 0"
></iframe>

If your page has a Content Security Policy, allow the frame with frame-src https://connect.desktopaccountingapi.com. A sandboxed iframe needs allow-downloads; without it the connector file download fails silently. allow-popups lets the help links open. With a redirectUrl, add allow-top-navigation-by-user-activation so the final button can return your customer to your app.

What your customer sees

The flow has six short steps. Each step has its own URL, so the browser’s back button works, and each page shows when the link expires.

Start. What will happen, roughly five minutes, and what your app can access. Social Security numbers and full credit card numbers are never shared.
Check your computer. The right computer (the one that keeps QuickBooks open, or the one hosting the file in a multi-user office), the company file open, signed in as Admin, single-user mode.
Download the connector file. A .qwc file named for your app and the company. Opening it adds your app to the QuickBooks Web Connector.
Allow access in QuickBooks. QuickBooks asks whether “Your App via Desktop Accounting API” may access the file. The page recommends Yes, always; allow access even if QuickBooks is not running.
Enter the password. A generated Web Connector password with a copy button. The customer pastes it into the Web Connector, saves it and turns on Auto-Run.
Test the connection. Live checks that tick off as they happen: the Web Connector checked in, QuickBooks opened the file, the company was identified, the connection test passed. If something fails, the page explains the cause and the fix in plain language, with a Check again button.

Your app’s name comes from the project’s App name setting in the dashboard. The connector freezes the name at installation, so renaming the project later does not force customers to authorize again.

The top of every page shows your organization’s display name and logo. Set them under Settings › Branding in the dashboard: the logo is a PNG, JPEG or WebP image of up to 256 KB, and the display name falls back to your organization name.

To see the flow before you build anything, open the setup flow demo. It walks through every step with sample data and connects nothing.

Connect QuickBooks Desktop in the help center walks through every screen. Link it from your own help pages.

When the customer finishes

With a redirectUrl, the last button sends the browser to:

https://app.example.com/settings/quickbooks/done?authSessionId=authsess_01j9...&status=completed

If the customer clicks Stop setup, they return with status=canceled instead. The redirect alone is not proof of a working connection, because anyone can open that URL. Confirm with a health check, or listen for the connection.setup_completed webhook, which fires after the first successful health check.

Expired and reused links

An expired link shows a page asking the customer to request a new link from your app. Create a new auth session; old ones cannot be extended. Creating a new auth session does not disturb a working connection.

Returning customers

When the end user already has a working or previously working connection, a new setup link opens on a What changed? page instead of the checklist. It shows when the Web Connector last checked in and offers:

Choice	What the flow does
I’m moving to a different computer	Tells them to turn off the old row, then runs setup on the new computer. Completing it revokes the old connector.
The company file moved or was renamed	Keeps the existing Web Connector row. Use the open file clears the stored path and tests the connection with the file now open in QuickBooks.
I restored a QuickBooks backup	Explains that an older backup loses the Web Connector registration (QBWC1079), then issues a new connector file.
I want to connect another company file	Explains that each file needs its own end user and setup link.
I reinstalled the Web Connector, or it showed QBWC1039	Walks through removing the old row and restarting the Web Connector, then issues a new connector file.
Something else	The normal setup steps with a new connector file.

So for most connection problems you only need to send a fresh setup link. A Having trouble? page in the flow shows the most likely cause, based on what the Web Connector reported, plus the full checklist.

Reconnecting

Run the same flow again when a customer:

Moves QuickBooks to a new computer. They open a new setup link on the new computer. When it completes, older Web Connector installations for this end user are turned off automatically. See Move the connection to a new computer.
Lost the Web Connector password or removed your app from the Web Connector.
Restored or copied the company file and the connection reports a mismatch. See Connection status.

Each run creates a new connector with a new password. The end user, its ID and your stored QuickBooks record IDs stay the same.