feat(quickbooks): support credential-scoped OAuth apps

Author: waleedlatif1

apps/docs/content/docs/integrations/quickbooks.mdx

@@ -11,7 +11,9 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
 />
 
 {/* MANUAL-CONTENT-START:intro */}
-Connect one QuickBooks Online company per credential. During OAuth, choose the company that the workflow should access; Sim binds that company to the credential automatically, so you do not enter a realm ID or API host.
+Connect one QuickBooks Online company per credential. Create an app in the Intuit Developer Portal, register `https://<your-sim-host>/api/auth/oauth2/callback/quickbooks` as its redirect URI, then enter that app's client ID and client secret in Sim and select its Sandbox or Production environment. Sim encrypts this app configuration on the credential and uses it for authorization, refresh, and revocation.
+
+During OAuth, choose the company that the workflow should access. Intuit returns the realm ID in the callback, and Sim verifies that the issued token can read CompanyInfo through that company-scoped API path before binding it to the credential, so you do not enter a realm ID or API host. The `CompanyInfo.Id` field is a separate entity ID and is not used as the realm ID.
 
 Master Data, Sales, and Purchasing transaction reads support **List** and **By ID** modes. List actions return at most one page. Use `nextStartPosition` in another workflow step when `hasMore` is true. Sim does not paginate, retry, or fetch related records automatically.
 
@@ -508,12 +510,12 @@ Create a Service or Non-inventory item in QuickBooks Online
 | --------- | ---- | -------- | ----------- |
 | `name` | string | Yes | Unique item name |
 | `itemType` | string | Yes | Writable item type: service or non_inventory |
-| `incomeAccountId` | string | No | Sales of Product Income account ID recording proceeds from the sale. Required for Service items, optional for Non-inventory items and for France locales |
+| `incomeAccountId` | string | No | Sales of Product Income account ID recording proceeds from the sale. Intuit requires it for Service items except in France locales |
 | `description` | string | No | Sales description |
 | `unitPrice` | number | No | Sales price per unit |
 | `purchaseDescription` | string | No | Purchase description |
 | `purchaseCost` | number | No | Purchase cost per unit |
-| `expenseAccountId` | string | Yes | Cost of Goods Sold account ID used to pay the vendor for this item. Required for both Service and Non-inventory items, except in France locales where it is optional |
+| `expenseAccountId` | string | No | Cost of Goods Sold account ID used to pay the vendor for this item. Intuit requires it for Service and Non-inventory items except in France locales |
 | `taxable` | boolean | No | Whether the item is taxable |
 | `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 

apps/docs/openapi-v2-resources.json

@@ -7498,6 +7498,90 @@
                   "additionalProperties": false
                 },
                 "description": "Authorization servers available for this OAuth service."
+              },
+              "fields": {
+                "maxItems": 20,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 255,
+                      "description": "Exact create-body field name."
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 255,
+                      "description": "Human-readable field label."
+                    },
+                    "placeholder": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1000,
+                      "description": "Suggested input placeholder."
+                    },
+                    "required": {
+                      "type": "boolean",
+                      "description": "Whether the field is required for the selected flow."
+                    },
+                    "secret": {
+                      "type": "boolean",
+                      "description": "Whether the submitted field is write-only secret material."
+                    },
+                    "multiline": {
+                      "type": "boolean",
+                      "description": "Whether the field is intended for multi-line input."
+                    },
+                    "requiredForAuthMethods": {
+                      "description": "Authentication methods for which this field is required.",
+                      "minItems": 1,
+                      "maxItems": 10,
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 64
+                      }
+                    },
+                    "options": {
+                      "description": "Fixed values accepted by a selector field.",
+                      "minItems": 1,
+                      "maxItems": 20,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "value": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 255,
+                            "description": "Submitted option value."
+                          },
+                          "label": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 255,
+                            "description": "Human-readable option label."
+                          }
+                        },
+                        "required": ["value", "label"],
+                        "additionalProperties": false
+                      }
+                    },
+                    "hint": {
+                      "description": "Provider-specific setup guidance.",
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 2000
+                    }
+                  },
+                  "required": ["id", "label", "placeholder", "required", "secret", "multiline"],
+                  "additionalProperties": false
+                },
+                "description": "Write-only setup fields required before starting this OAuth flow."
               }
             },
             "required": [
@@ -7508,7 +7592,8 @@
               "providerFamily",
               "available",
               "supportsReconnect",
-              "authorizationOptions"
+              "authorizationOptions",
+              "fields"
             ],
             "additionalProperties": false
           },
@@ -7710,6 +7795,7 @@
                 "providerFamily": "salesforce",
                 "available": true,
                 "supportsReconnect": true,
+                "fields": [],
                 "authorizationOptions": [
                   {
                     "providerId": "salesforce",
@@ -7905,6 +7991,31 @@
                 "minLength": 1,
                 "maxLength": 255,
                 "description": "Name shown for the new credential in Sim."
+              },
+              "oauthClientConfig": {
+                "description": "Write-only OAuth app configuration when required by the provider.",
+                "type": "object",
+                "properties": {
+                  "clientId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "description": "Client ID for the caller-managed Intuit OAuth application."
+                  },
+                  "clientSecret": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512,
+                    "description": "Write-only client secret for the caller-managed Intuit OAuth application."
+                  },
+                  "environment": {
+                    "type": "string",
+                    "enum": ["sandbox", "production"],
+                    "description": "Intuit company environment used for authorization and API requests."
+                  }
+                },
+                "required": ["clientId", "clientSecret", "environment"],
+                "additionalProperties": false
               }
             },
             "required": ["workspaceId", "providerId", "displayName"],
@@ -7924,6 +8035,31 @@
                 "minLength": 1,
                 "maxLength": 255,
                 "description": "Existing OAuth credential to reconnect in place."
+              },
+              "oauthClientConfig": {
+                "description": "Write-only OAuth app configuration when required by the provider.",
+                "type": "object",
+                "properties": {
+                  "clientId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "description": "Client ID for the caller-managed Intuit OAuth application."
+                  },
+                  "clientSecret": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512,
+                    "description": "Write-only client secret for the caller-managed Intuit OAuth application."
+                  },
+                  "environment": {
+                    "type": "string",
+                    "enum": ["sandbox", "production"],
+                    "description": "Intuit company environment used for authorization and API requests."
+                  }
+                },
+                "required": ["clientId", "clientSecret", "environment"],
+                "additionalProperties": false
               }
             },
             "required": ["workspaceId", "credentialId"],

apps/sim/.env.example

@@ -153,11 +153,6 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # TIKTOK_CLIENT_ID=
 # TIKTOK_CLIENT_SECRET=
 
-# QuickBooks Online OAuth (Optional - credentials from the Intuit Developer Portal)
-# QUICKBOOKS_CLIENT_ID=
-# QUICKBOOKS_CLIENT_SECRET=
-# QUICKBOOKS_ENV=sandbox                         # Required when QuickBooks is configured: sandbox or production
-
 # Azure Blob Storage
 # AZURE_ACCOUNT_NAME=                             # Azure storage account name
 # AZURE_ACCOUNT_KEY=                              # Azure storage account key

apps/sim/app/api/auth/[...all]/route.test.ts

@@ -60,7 +60,6 @@ vi.mock('@/app/api/credential-groups/oauth-callback', () => ({
   handleCredentialGroupOAuthCallback: handlerMocks.credentialGroupCallback,
 }))
 
-import { getQuickBooksCallbackRealm } from '@/lib/oauth/quickbooks'
 import { GET, POST } from '@/app/api/auth/[...all]/route'
 
 afterAll(resetEnvFlagsMock)
@@ -133,68 +132,6 @@ describe('auth catch-all route managed OAuth callbacks', () => {
   })
 })
 
-describe('auth catch-all route QuickBooks callback', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    setEnvFlags({ isAuthDisabled: false })
-  })
-
-  it('binds the callback realm only while Better Auth processes the OAuth response', async () => {
-    const { NextResponse } = await import('next/server')
-    handlerMocks.betterAuthGET.mockImplementationOnce(async () => {
-      await Promise.resolve()
-      expect(getQuickBooksCallbackRealm()).toBe('123456789')
-      return new NextResponse(null, { status: 302 })
-    })
-    const request = createMockRequest(
-      'GET',
-      undefined,
-      {},
-      'http://localhost:3000/api/auth/oauth2/callback/quickbooks?code=test&state=test&realmId=123456789'
-    )
-
-    const response = await GET(request)
-
-    expect(response.status).toBe(302)
-    expect(handlerMocks.betterAuthGET).toHaveBeenCalledOnce()
-    expect(() => getQuickBooksCallbackRealm()).toThrow(/did not include a company identity/)
-  })
-
-  it('delegates a denied callback without requiring a realm', async () => {
-    const { NextResponse } = await import('next/server')
-    handlerMocks.betterAuthGET.mockImplementationOnce(async () => {
-      expect(() => getQuickBooksCallbackRealm()).toThrow(/did not include a company identity/)
-      return new NextResponse(null, { status: 302 })
-    })
-    const request = createMockRequest(
-      'GET',
-      undefined,
-      {},
-      'http://localhost:3000/api/auth/oauth2/callback/quickbooks?error=access_denied&state=test'
-    )
-
-    const response = await GET(request)
-
-    expect(response.status).toBe(302)
-    expect(handlerMocks.betterAuthGET).toHaveBeenCalledOnce()
-  })
-
-  it.each([
-    ['missing', 'http://localhost:3000/api/auth/oauth2/callback/quickbooks?code=test&state=test'],
-    [
-      'invalid',
-      'http://localhost:3000/api/auth/oauth2/callback/quickbooks?code=test&state=test&realmId=not-a-company',
-    ],
-  ])('rejects a %s callback realm before Better Auth exchanges the code', async (_, url) => {
-    const request = createMockRequest('GET', undefined, {}, url)
-
-    const response = await GET(request)
-
-    expect(response.status).toBe(400)
-    expect(handlerMocks.betterAuthGET).not.toHaveBeenCalled()
-  })
-})
-
 describe('auth catch-all route (DISABLE_AUTH get-session)', () => {
   beforeEach(() => {
     vi.clearAllMocks()

apps/sim/app/api/auth/[...all]/route.ts

@@ -9,7 +9,6 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { isCredentialGroupOAuthState } from '@/lib/credential-groups/oauth-state'
 import { getCredentialGroupStandardOAuthProviderFromProviderId } from '@/lib/credential-groups/providers'
 import { enforcePublicCredentialGroupIpRateLimit } from '@/lib/credential-groups/rate-limit'
-import { normalizeQuickBooksRealmId, withQuickBooksCallbackRealm } from '@/lib/oauth/quickbooks'
 import { handleCredentialGroupOAuthCallback } from '@/app/api/credential-groups/oauth-callback'
 
 export const dynamic = 'force-dynamic'
@@ -107,30 +106,6 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     return NextResponse.json(createAnonymousSession())
   }
 
-  if (path === 'oauth2/callback/quickbooks') {
-    const authorizationCode = request.nextUrl.searchParams.get('code')
-    if (!authorizationCode) return betterAuthGET(request)
-
-    const realmId = request.nextUrl.searchParams.get('realmId')
-    if (!realmId) {
-      return NextResponse.json(
-        { error: 'QuickBooks callback did not include a company identity.' },
-        { status: 400 }
-      )
-    }
-
-    try {
-      normalizeQuickBooksRealmId(realmId)
-    } catch {
-      return NextResponse.json(
-        { error: 'QuickBooks callback included an invalid company identity.' },
-        { status: 400 }
-      )
-    }
-
-    return withQuickBooksCallbackRealm(realmId, () => betterAuthGET(request))
-  }
-
   return betterAuthGET(request)
 })
 

apps/sim/app/api/auth/oauth/token/route.test.ts

@@ -48,6 +48,7 @@ vi.mock('@/lib/credentials/application/resolve-managed-oauth-token', () => ({
 vi.mock('@/tools/metadata', () => ({ getToolMetadata: mockGetToolMetadata }))
 
 import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
+import { createQuickBooksAccountId } from '@/lib/oauth/quickbooks'
 import { GET, POST } from '@/app/api/auth/oauth/token/route'
 
 describe('OAuth Token API Routes', () => {
@@ -104,7 +105,11 @@ describe('OAuth Token API Routes', () => {
       })
       authOAuthUtilsMockFns.mockGetCredential.mockResolvedValueOnce({
         id: 'credential-id',
-        accountId: 'quickbooks:123456789:intuit-subject-01234567-89ab-4def-8abc-0123456789ab',
+        accountId: createQuickBooksAccountId(
+          '123456789',
+          'intuit-subject-01234567-89ab-4def-8abc-0123456789ab',
+          'sandbox'
+        ),
         accessToken: 'test-token',
         refreshToken: 'refresh-token',
         accessTokenExpiresAt: new Date(Date.now() + 3600 * 1000),
@@ -126,6 +131,7 @@ describe('OAuth Token API Routes', () => {
         accessToken: 'fresh-token',
         credentialType: 'oauth',
         realmId: '123456789',
+        quickBooksEnvironment: 'sandbox',
       })
     })