Procedure for connecting external services (QBO/Xero, AI providers, payment gateways, email providers, e-sign, video, calendar) at firm-level. Most integrations are admin-only one-time setup; per-engagement linkage happens later in respective workflows.

- New firm onboarding — Setup Wizard prompts integration connections - Adding new integrations as the firm grows (e.g. adding CPACharge after starting with Stripe) - Replacing an integration (e.g. switching from DocuSign to HelloSign) - Re-authorizing expired tokens (QBO 60-day expiry; OAuth refresh failures)

- Primary owner: Firm Admin or OWNER - Integration-specific: e.g. accounting team owner verifies QBO connect; IT/security signs off on AI provider keys - Each integration goes through Settings → Integrations (single connect surface per Module 36)

- Firm Profile complete - Admin role (OWNER or ADMIN) - API keys / OAuth credentials for the target service (firm-supplied, not platform-supplied) - ENCRYPTION_KEY configured at platform level (set by ProDeskCPA admin in Vercel env, not firm-managed)

1. Settings → Integrations → see category-grouped cards (AI / Storage / Meeting / Accounting / Tax / Email / Payment / E-Sign / Communications) 2. For each integration to connect, click the card → Connect modal opens with type-specific field schema 3. Per-integration steps: **QBO / Xero (M-021):** Click Connect → OAuth flow → grant access to firm's accounting software → Realm ID (QBO) or tenant ID (Xero) auto-populated → Status flips to "✓ Connected" - 60-day token expiry; system reminds 7 days before; click Re-Authorise to refresh **AI Providers (M-022):** Per provider card (Anthropic / OpenAI / Gemini / Perplexity / Mistral / Cohere / Grok), click Connect → API Key form OR OAuth (Gemini OAuth path) → Save → key encrypted AES-256-GCM → Test Connection runs canonical test - Set primary provider (default Gemini) + fallback ordering - Configure preferred model per provider via ⚙️ **Email (M-025):** Per provider (Gmail / Outlook / Yahoo / Zoho / IMAP), click Connect → OAuth (Gmail/Outlook/Zoho) OR IMAP credentials (Yahoo / generic IMAP) → host + port + display name - Two account types: PERSONAL (user's mailbox) vs FIRM (billing@firm.com etc.) - Verify auto-sync runs every 1 minute after connect **Payment (M-010 / M-005):** Per gateway (Stripe / Square / PayPal / LawPay / CPACharge), click Connect → OAuth (Stripe Connect) OR API key form - For each: also configure webhook URL in provider's dashboard pointing to ProDeskCPA's webhook endpoint - Webhook secrets stored separately, used for signature verification on incoming calls **E-Sign (M-026):** DocuSign / HelloSign — OAuth or API key - Configure default signing flow (sequential vs parallel) + KBA defaults **Meeting Platforms (M-035):** Zoom / Google Meet / Teams / Webex / Whereby / Jitsi / Daily / GoTo - Per platform card: Connect → OAuth or API key - Mark ONE as DEFAULT (firm-wide; used by Calendar/Booking auto-create) **Tax Software:** Drake / Lacerte / UltraTax / ProSeries / ProConnect / CCH Axcess - File-based: no connection needed; just configure default target in Settings - API-based (ProConnect / CCH Axcess): OAuth flow 4. Test each integration after connect: Test Connection button (where available); for accounting connect, run a TB import; for payment, verify webhook arrival; for email, confirm 1-minute sync 5. AuditLog row written for every connection event (M-004); review under Settings → Security & Audit

- If integration test fails: review error message; common causes are wrong scopes, expired API key, IP restrictions on provider side - For meeting platforms with multiple options: choose firm DEFAULT based on existing tooling; firm-wide setting (NOT per-user) - For payment, support multiple gateways simultaneously — useful for different client segments (e.g. Stripe for cards, LawPay for trust accounts) - If ENCRYPTION_KEY rotates at platform level: ALL stored credentials become unreadable — coordinate with ProDeskCPA admin BEFORE rotation; emergency re-connect of all integrations would be required

- QBO Desktop NOT supported (no OAuth API): convert to QBO Online OR migrate to Xero - 4 of 9 webhook handlers (PayPal-platform, Authnet, PayPal-billing, Square) are fail-closed gates ONLY — real signature verification deferred; do NOT set their env vars (PAYPAL_WEBHOOK_ID, AUTHNET_WEBHOOK_SECRET, SQUARE_WEBHOOK_SIGNATURE_KEY) until verification implemented (M-005 honest status) - AI provider failure during a call: callBrain returns BrainProviderResult with status "error" + populated error field; OTHER providers still respond (Promise.allSettled isolation) - White-label send architecture for email is UNRESOLVED (Module 25 A/B/C decision pending) — until decided, all outbound mail still routes via SendGrid as noreply@prodeskcpa.com - One QBO company can be referenced by multiple engagements (e.g. multi-year audit) — each engagement holds its own qboRealmId for safety - Personal vs firm email distinction at the EmailAccount level (isPersonal flag) — important for white-label send architecture once decided

- Mandatory P0 integrations connected before first client onboarded: QBO/Xero, Email, AI Brain, E-Sign, Stripe (or chosen payment) - Test Connection passes 100% before relying on integration in production - Token expiry monitoring: 0 expired tokens in any 30-day rolling window (proactive Re-Authorise) - Audit log shows successful connection events for every claimed integration (no silent failures)

- Modules: M-021 QBO/Xero · M-022 AI Brain · M-025 Email · M-026 E-Sign · M-010 Billing · M-005 Webhooks · M-035 Video · M-034 Calendar · M-036 Settings · M-038 API Keys · M-004 AuditLog - SOPs: SOP-009 (new staff member — needs email connection) · SOP-011 (branding setup) · SOP-012 (compliance evidence — depends on AuditLog from connections)

- Per-firm credentials override env fallbacks for AI providers; env fallbacks fill gaps for providers not connected at firm level (M-022) - "Keys are stored encrypted in your database" assurance surfaced in every credential modal — AES-256-GCM is the at-rest encryption - Pre-built RULE_TEMPLATES in Workflows (M-024) include "Payment → Unlock Portal" — depends on Stripe webhook being properly connected - Operator action pending in Vercel (carry-forward): set ZOHO_ACCOUNT_ID, AUTH_URL; verify STRIPE_WEBHOOK_SECRET / STRIPE_PLATFORM_WEBHOOK_SECRET / RAZORPAY_WEBHOOK_SECRET set