Skip to content

QuickBooks Time Production Setup

  • Status: CURRENT PROVIDER SETUP RUNBOOK
  • Owns: approved QuickBooks Time production setup and disconnect procedure
  • Does not own: provider onboarding approval, current token state or deployment authorization
  • Update when: the approved Intuit app, OAuth, sync or disconnect procedure changes

Intuit App Detail URLs

Use these production values for the Intuit Developer app detail checklist:

Field Value
Host domain ctclogistic.com
Launch URL https://ctclogistic.com/login.php
Connect/Reconnect URL https://ctclogistic.com/quickbooks-time/connect
Disconnect URL https://ctclogistic.com/quickbooks-time/disconnect
Redirect URI https://ctclogistic.com/quickbooks-time/callback
Privacy policy URL https://ctclogistic.com/privacy-policy
EULA / terms URL https://ctclogistic.com/terms-of-use

The production hosted location already entered in Intuit is United States with 44.232.78.19 and 44.228.202.51, based on the current ctclogistic.com A records.

Environment Values

Existing staff-time sync remains token-first and silent:

QUICKBOOKS_TIME_ACCESS_TOKEN=
QUICKBOOKS_TIME_REGULAR_JOBCODE_ID=0
QUICKBOOKS_TIME_BREAK_10_JOBCODE_ID=3641011
QUICKBOOKS_TIME_LUNCH_JOBCODE_ID=3641009

QUICKBOOKS_TIME_REGULAR_JOBCODE_ID=0 preserves the existing QuickBooks Time regular clock-in/out behavior where loader work is recorded without a jobcode. Existing QuickBooks Time break buttons are preserved by using 10 Min Break (3641011, paid break) and Lunch Break (3641009, unpaid break).

OAuth app setup uses these additional values when the app credentials are available:

QUICKBOOKS_TIME_CLIENT_ID=
QUICKBOOKS_TIME_CLIENT_SECRET=
QUICKBOOKS_TIME_REDIRECT_URI=https://ctclogistic.com/quickbooks-time/callback
QUICKBOOKS_TIME_PUBLIC_BASE_URL=https://ctclogistic.com
QUICKBOOKS_TIME_CTC_CLIENT_ID=1
QUICKBOOKS_TIME_SETUP_TOKEN=

QUICKBOOKS_TIME_CTC_CLIENT_ID controls which CTC tenant receives OAuth token values in T_TENANT_CONFIG. If it is omitted, the default Config::CLIENT_ID tenant is used. QUICKBOOKS_TIME_SETUP_TOKEN is recommended for production setup. When present, use /quickbooks-time/connect?setup_token=<token> only for the initial OAuth connection while no QuickBooks Time access token is configured for the tenant. After a tenant token exists, reconnect requires an authenticated CTC tenant administrator or super admin session. For disconnect, send an internal POST to /quickbooks-time/disconnect with setup_token=<token>, or use the authenticated CTC tenant administrator disconnect form, which includes a session CSRF token. Do not place the setup token in the Intuit Developer Disconnect URL. If the setup token is omitted, setup requires an authenticated CTC tenant administrator session.

Runtime Behavior

  • /quickbooks-time/connect redirects to the QuickBooks Time OAuth authorization URL when client credentials are configured and the request has an authenticated CTC tenant administrator session, super admin session, or a valid setup token before any QuickBooks Time access token is configured for the tenant.
  • /quickbooks-time/callback validates OAuth state, verifies that the state came from an authorized setup request, exchanges the authorization code for tokens, stores the access token in T_TENANT_CONFIG.QUICKBOOKS_TIME_ACCESS_TOKEN for QUICKBOOKS_TIME_CTC_CLIENT_ID, stores refresh/expiry metadata for operations, stores only a safe masked result in the session, then redirects to the same path without OAuth query parameters before rendering the result page. Token values are masked in the page/log output and are never rendered in full.
  • Staff-time sync already reads T_TENANT_CONFIG.QUICKBOOKS_TIME_ACCESS_TOKEN before falling back to the deployment env value, so a successful OAuth callback makes the token available to the existing silent sync path.
  • If the stored OAuth access token is expired, within five minutes of expiry, or has a refresh token but no expiry metadata, staff-time sync refreshes it through the QuickBooks Time /grant refresh-token flow before making the API request.
  • /quickbooks-time/disconnect is the public Intuit disconnect landing URL. GET requests only show administrator disconnect instructions and, for authorized administrator sessions, a CSRF-protected disconnect form. It clears stored tenant QuickBooks Time token metadata only on POST with a valid setup token or with an authenticated CTC tenant administrator/super admin session plus a valid CSRF token. If a deployment-level QUICKBOOKS_TIME_ACCESS_TOKEN secret is also configured, remove that secret to fully disable sync.
  • /privacy-policy and /terms-of-use describe QuickBooks Time data flow, staff-time event synchronization, integration credentials, disconnect requests, retention, user responsibilities, and third-party service terms for Intuit production review.
  • /api/quickbooks-time/connect, /api/quickbooks-time/callback, and POST /api/quickbooks-time/disconnect expose the same integration flow for API checks.
  • Loader check in, check out, break in, and break out behavior does not change visually. Staff-time sync still runs after the CTC write has committed.
  • Staff-time sync follows the existing QuickBooks Time operating model: regular loader time may use no jobcode, while break and lunch use the existing QuickBooks Time break jobcodes. Sync only closes or updates active timesheets that match the configured staff-time model or CTC notes/event markers. If another QuickBooks Time timesheet is already active, CTC leaves it unchanged and logs manual_review_required.
  • Manager-created, edited, and deleted staff-time corrections also schedule a silent QuickBooks Time correction sync after the CTC write has committed. Deleting a CLOCK_OUT or BREAK_OUT event does not reopen a historical QuickBooks Time timesheet; it logs a manual-review result instead.

QuickBooks Time OAuth documentation: https://tsheetsteam.github.io/api_docs/#authentication

---

Source: docs/runbooks/QUICKBOOKS_TIME_PRODUCTION_SETUP_RUNBOOK.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.