Connect QuickBooks (Web Connector)

TenkeyBridge talks to QuickBooks Desktop and Enterprise through QuickBooks Web Connector (QBWC) — the small client Intuit ships with every Desktop and Enterprise install. There is nothing to download or install next to QuickBooks: you open one .qwc file, paste a one-time password, and the realm is connected.

Who this is for

Everyone connecting a QuickBooks Desktop or Enterprise company file to TenkeyBridge. It works on your own machine, on an RDS host, and — the case it was designed around — on hosted desktops such as Rightworks (formerly Right Networks), where a standard Windows user can't write an .exe anywhere or open cmd.exe, and the provider documents Web Connector as the approved way for a third-party service to talk to QuickBooks. If your QuickBooks lives on Rightworks, read this page for the concepts and then follow Connect TenkeyBridge on Rightworks for the hosting-provider-specific steps (getting the file onto the hosted desktop, asking support to auto-start things at logon, and the exact wording to use in a support ticket).

See Latency for what to expect from a poll-based transport.

How it works

Web Connector is a small client bundled with every copy of QuickBooks Desktop and Enterprise. Once you point it at TenkeyBridge, it calls our https://qbwc.tenkeybridge.com/qbwc endpoint on a schedule — by default every 10 seconds — and asks "any work for me?"

• Most polls do nothing. If nothing is queued for your realm, the answer costs one HTTPS round trip and QuickBooks is never opened, never touched. Only when your integration actually makes an API call does the next poll come back with work.
• QuickBooks opens only when there's a request waiting. The poll that finds work has TenkeyBridge hand it the qbXML for that request; Web Connector opens (or attaches to) the company file, runs it through QuickBooks, and posts the result back.
• The session stays open for about ten more seconds after the last request, in case another one arrives — a read-then-write sparse update, an iterator walking a large list, or just a burst of calls from your integration all land inside that window and run back-to-back without reopening QuickBooks each time. Opening a QuickBooks session is the expensive step, so keeping it open briefly is what makes a burst of requests fast after the first one.
• Your REST calls don't change at all. Same OAuth clients, same realm ids, same JSON request and response shapes, same fault codes. Web Connector is invisible above the transport layer — the REST API neither knows nor cares that a poll carried your qbXML; the only thing you'll notice is latency.

Set up in four steps

1. Portal → your realm → "Connect with QuickBooks Web Connector" → Create connector. The portal shows a one-time password (shown once — copy it before moving on) and a Download .qwc button that saves a file named TenkeyBridge-<realm>.qwc.

2. On the QuickBooks desktop, with the company file open: open Web Connector (it's already installed alongside QuickBooks — look for it in the Windows Start menu, or QuickBooks' File → App Management → Update Web Services), choose Add an Application, and pick the .qwc file you downloaded. QuickBooks shows its integrated-application grant dialog with two real choices:

   • "Yes, whenever this QuickBooks company file is open" — works, but QuickBooks has to already be open on this file every time Web Connector polls.
   • "Yes, always; allow access even if QuickBooks is not running" — recommended. This grants unattended mode: Web Connector can launch QuickBooks in the background and open the pinned company file itself, so all you need is a live Windows session with Web Connector running — not QuickBooks sitting open on screen.

   (A third option, "No", declines the grant entirely — don't pick that one.)

   The first call after a quiet period is slow

   The "Yes, always" grant is the right default, but know what it costs: when QuickBooks is fully closed, the first request after that makes Web Connector launch QuickBooks and open the company file from cold — in our tests that took about 30 seconds (26–27 s, unattended, nobody at the machine). The gateway waits up to 4 minutes for a Web Connector request, so that first call completes with a normal 200; it just takes a while. QuickBooks exits again after each unattended session, so this cost recurs on every first request after a quiet period. For a more responsive integration, keep QuickBooks open on the pinned file — the grant still covers reconnects if Web Connector needs to relaunch it.

   The 4-minute budget is deliberately generous, because the launch can stall on the host machine for reasons that have nothing to do with TenkeyBridge. The one we hit ourselves: after a Windows update, every Web Connector launch of QuickBooks raised a Windows UAC prompt ("QuickBooks Utility Application is requesting your permission"), and an unattended launch sat behind it until someone clicked Yes — once. After that one click the prompt stopped and the 30-second number came back. If your first calls after a quiet period are timing out, look at the host's screen before anything else.

   You only see 504 AGENT_TIMEOUT if the launch takes longer than the 4-minute budget. If that happens, the work may still complete in the background: re-query before retrying a write, never blindly retry one.

3. Web Connector prompts for a password. Paste the one-time password from the portal. It's never shown again after this step, so if you didn't copy it, revoke the connector in the portal and create a fresh one.

4. Tick Auto-Run on the new entry in Web Connector's list, and set its interval to match (10 seconds by default — Web Connector's own UI floor is one minute for manual editing, but the .qwc file already requests the faster interval, so leave it as imported). Within one poll — a few seconds — the portal's status badge flips from Offline to Web Connector online, along with the pinned company file's name once the first session runs.

Which company file

QuickBooks can only have one company file open per running instance, so TenkeyBridge has to be certain which file a given connector talks to.

• The first successful session pins it. The first request Web Connector runs after you complete setup carries the open file's path and name; TenkeyBridge records that as the connector's company file from then on.
• Every session after that opens the pinned file explicitly — Web Connector doesn't just use "whatever's currently open," it's told which file to open.
• If a different file is open when Web Connector goes to run a request (someone opened another company on that machine, for instance), QuickBooks can't serve both at once. Web Connector reports the failure back to us, and every request queued for that realm fails with AGENT_EXECUTION_ERROR (502; the code's name is historical — the message itself says Web Connector) whose detail names the sub-code QB_COMPANY_FILE_UNAVAILABLE; the portal's realm page shows which file is pinned and which one was open, in the connector's "last error." Your requests are refused outright rather than silently running against the wrong company's data.
• Fix it either by opening the pinned file again, or — if you genuinely moved or renamed the company file — click Unpin on that connector in the portal. The next session pins whatever file is open at that point, same as the first time.

Multiple company files

One Web Connector entry serves exactly one company file and one realm. If you have more than one company file to connect:

• Create a separate connector (and download a separate .qwc) per company file, each with its own username, password, and realm.
• Add all of them to the same Web Connector installation. Web Connector serializes them — QuickBooks only ever has one company open at a time, so it works through each connector's queued requests in turn rather than running them concurrently.
• With QuickBooks closed and every connector granted "Yes, always," Web Connector opens each pinned file itself as that connector's queue needs it, closing one and opening the next. With QuickBooks kept open on one particular file, only that file's connector is actually served until you switch files or close QuickBooks.

Latency

Web Connector trades a little latency for zero installs, by design — see Poll-and-hold above for why. Concretely, on the default 10-second poll:

• First request after a period of no activity: up to the poll interval (worst case ~10 s) waiting for Web Connector's next check-in, plus the time QuickBooks takes to open the session (typically a few seconds). Call it "up to 15 seconds or so" for planning purposes.
• Follow-up requests within about 10 seconds of the previous one: land inside the session-idle hold with QuickBooks already open, so they cost roughly a second — one SOAP round trip plus execution.
• Measured numbers: on a Windows 11 box running QuickBooks Enterprise 24 and Web Connector 2.3, against the gateway in Fly's sjc region, at the default 10-second poll: a first request after ≥30 s idle came back with a median of 3.2 s (3.1–3.7 s across 3 runs), and follow-up requests inside the session-idle hold came back with a median of 0.7 s (0.63–0.77 s across 12+ samples). An InvoiceAdd took 1.7 s and the read-back to confirm it took 0.7 s.
• First request after QuickBooks was closed (unattended grant): Web Connector launches QuickBooks and opens the company file first. Measured on the same box, unattended, with QuickBooks fully exited before each run: 26.0 s and 26.7 s end to end (poll wait + QuickBooks launch + company-file open + the query), and follow-ups inside the hold at 0.92–0.96 s. That is well inside the gateway's 4-minute Web Connector budget; the headroom exists for launches that stall on the host machine (see the warning under Set up in four steps — a Windows UAC prompt held one of our launches for as long as nobody clicked it).

Troubleshooting

Symptom	Meaning	Fix
Web Connector's Status column shows QBWC1012, QBWC1041, QBWC1042, QBWC1043, QBWC1044, or QBWC1045	Web Connector couldn't reach, or got an error back from, the TenkeyBridge endpoint during that step of the call sequence	Check https://tenkeybridge.betteruptime.com for an ongoing incident. If the status page is clear, check the machine's own internet connection; Web Connector doesn't retry automatically, so run the update again once connectivity is back
Add an Application fails with QBWC1048: QuickBooks Web Connector could not verify the web application server certificate (and QBWC1051: The new application was not added)	Your .qwc points at api.tenkeybridge.com — a file issued before 2026-09-22. Current .qwc files point Web Connector at qbwc.tenkeybridge.com, whose certificate chains to a root that ships in Windows itself, so this error no longer occurs on locked-down or hosted desktops. On a hosted desktop behind a corporate web filter the same error can also mean the filter is serving a block page for the address — see the Rightworks troubleshooting table for the check	Create a new Web Connector connection for the realm in the portal and add that .qwc instead. (Legacy fallback for an old .qwc: install https://letsencrypt.org/certs/isrgrootx1.der into your own user's Trusted Root store — but that does not make the connection stable on hosted desktops; get a current .qwc.)
Web Connector's Status column shows nvu and the row goes red	The password Web Connector has stored doesn't match the connector's current password (wrong at setup, or the connector was revoked and recreated)	Passwords aren't recoverable or resettable in place — revoke the connector in the portal, create a new one, and re-add the resulting .qwc to Web Connector with the new password
The portal shows the connector as Offline	Web Connector isn't running on the host machine, Auto-Run is off, or the Windows/Rightworks session it runs in has disconnected	Confirm Web Connector is open and Auto-Run is ticked on that entry; on a hosted desktop, make sure the session is still connected (see the Rightworks guide)
Your app's first calls of the day fail with 503 AGENT_OFFLINE, then start working a few minutes later	The app called before Web Connector had checked in — QuickBooks or Web Connector wasn't open yet on the host machine, so nothing was serving the realm	Nothing was sent to QuickBooks, so these calls are always safe to retry, writes included (see AGENT_OFFLINE). Open QuickBooks and Web Connector before starting your app, or have your app retry AGENT_OFFLINE with a backoff
Requests keep failing with QB_COMPANY_FILE_UNAVAILABLE	The wrong company file is open on that machine — see Which company file	Open the pinned file, or Unpin in the portal if the file legitimately moved
504 AGENT_TIMEOUT on the first request after QuickBooks was closed	The Web Connector launch of QuickBooks under the "Yes, always" unattended grant took longer than the gateway's 4-minute budget. A healthy launch takes about 30 s, so this almost always means the launch is stalled on the host — most often a dialog or a Windows UAC prompt ("QuickBooks Utility Application is requesting your permission") waiting for a click — see The first call after a quiet period is slow. The code is named after the original transport; the message itself says Web Connector.	Look at the host machine's screen and answer whatever QuickBooks or Windows is asking; the request may still have completed in the background, so re-query before retrying a write — or send writes with a requestid so a retry is safe (Safe retries). On a hosted desktop that is consistently slower than 4 minutes, keep QuickBooks open on the pinned file
The Every-Min box on the row is blank, or you typed a number into it and now requests take up to a minute to start	Blank is normal: the .qwc sets a 10-second poll, and Web Connector's UI can only display whole minutes. Typing a value overrides the file's setting, and the UI refuses anything below 1 minute afterwards	Leave Every-Min alone. If you already changed it, Remove the row and Add an Application again with the same .qwc (QuickBooks remembers the grant; re-enter the password). The 10-second poll comes back with the file
Nothing works and the above doesn't explain it	—	Revoke the connector and create a fresh one; a clean .qwc and password rule out most stuck state

Repeated nvu failures on one username are rate-limited server-side (five bad attempts in a minute locks that username out for 60 seconds) as a guard against password guessing — if you're mid-troubleshooting and see that, wait a minute rather than hammering retries.

Security

• The password you type into Web Connector is never stored in the clear — TenkeyBridge only keeps its hash. It's shown to you exactly once, at creation, and can't be retrieved later — only reset by revoking and recreating the connector.
• The .qwc file itself carries no secret. It's a small XML document naming the endpoint, your username, and a couple of identifiers — the password isn't in it at all, because QuickBooks' own protocol has you type the password into Web Connector directly, which then stores it encrypted in the Windows registry. That means the .qwc file is safe to download over a hosted browser session or email to yourself — there's nothing in it worth protecting beyond knowing which realm it points at.
• The endpoint only accepts HTTPS — QuickBooks Web Connector itself refuses to add a non-HTTPS application URL for anything other than localhost, so this isn't optional even by mistake.
• Revoke a connector any time from the portal. Web Connector keeps polling on its own schedule and gets nvu on every poll from then on — its row in Web Connector shows an error each time — until you add a new connection. Once a connector is revoked you can delete it from the list in the portal (owners and admins); active connectors must be revoked first.