fix(zendesk,gong): mark org-wide baseUrl fields as auth_config_field

@zen-agentchecks n/achecks…zen/fix-org-wide-baseurl-field-type-kucz0p → master2 files · +4 −2updated 1mo ago

▸Description· 1 comment

Description

When a customer connects Zendesk via Composio, every team member is prompted to enter the company's Zendesk subdomain (e.g. `moderntreasury1775068997`). Same for Gong's API base URL. Both values are properties of the organization, not the individual user — they should be set once when the integration is wired up, then inherited by every connection under that auth config.

This PR flips one field on each of two toolkits (`apps/zendesk/config.ts:14`, `apps/gong/config.ts:52`) from `field_type: 'connection_field'` to `'auth_config_field'`.

Customer evidence (urgent enterprise blockers)

Allvue Systems / Keith Costello (Gong) — user asked to configure redirect URI in Gong's developer portal instead of getting a Composio-managed OAuth consent screen. Root cause includes the per-connection base-URL prompt breaking assumptions about a single configured integration.
Modern Treasury / Terence Li (Zendesk) — direct quote: "every team member asked for subdomain even though the org already has it configured."

⚠️ CI guardrail flagged this — and it's right to be cautious

Mercury's `ci_checks/check_config_breaking_changes.py` correctly flagged this as a breaking change, with the documented escape hatch: `# ci-skip: config-breaking-changes ()` comment at the top of each file. Both files now carry the skip with a pointer to this PR.

The breaking-change concern is real and worth understanding before merging:

New connections under brand-new auth configs: ✅ work correctly. Admin enters subdomain at AC creation; new connections inherit it.
Existing connections: ✅ continue to work. They have `subdomain` in their connection state already; the runtime templating in `apps/apollo/src/lib/connected_accounts/getAuthorizationParams.ts` reads from connection state.
New connections under EXISTING auth configs: ⚠️ may break. Existing auth configs don't have `subdomain` stored in `nonSensitiveConfig` (it was never collected at AC creation time). When a new user tries to create a connection under an existing AC, Apollo's URL templating won't have a subdomain to fill the authorize URL, and the connection-form will no longer prompt for it (because it's no longer a `connection_field`).

This last case is what makes the breaking-change check fire. Two paths forward, neither in this PR:

Apollo-side fallback: in the field-routing logic at `apps/apollo/src/lib/auth_config/utils/fieldGenerator.ts:402-421` and `apps/apollo/src/lib/toolkits/get_toolkits_by_slug.ts:224-229`, when an `auth_config_field` is missing from a particular auth config, fall back to prompting on the connection form. Backwards-compatible behavior.
One-time data migration: for each existing auth config of these toolkits, read the most recent ACTIVE connection's `subdomain` value from connection state and write it to the auth config's `nonSensitiveConfig`. Then remove the connection-level prompt cleanly.

I'd lean toward (1) — it's a smaller blast radius and self-heals. Reviewer / platform team should sign off on the approach before this merges, or batch with a tiny Apollo PR that adds the fallback.

Why this is a one-line fix on the toolkit side

`packages/auth-config` already supports both routing modes — see `packages/auth-config/src/tests/bearer_token_injection.test.ts:109+` ("copies auth_config_field baseUrl fields (Braintree-style)") for the test. Apollo's `fieldGenerator.ts` and `get_toolkits_by_slug.ts` partition fields into auth-config-form vs connection-form purely by `field_type`. The toolkit-side change is genuinely one character per file — but the migration concern above is the reason the CI guardrail exists.

Behavior

Scenario	Before	After
New auth config, new connection	Admin: client_id/secret/scopes → User: subdomain	Admin: client_id/secret/scopes/subdomain → User: nothing extra
Existing auth config, existing connection	Continues to work	✅ Continues to work
Existing auth config, NEW connection	User prompted for subdomain	⚠️ Apollo fallback or migration needed (see above)

Out of scope (intentionally narrow)

27 other Mercury toolkits also declare org-wide-looking baseUrl fields as `connection_field`:

``` egnyte, snowflake, pipedrive, recruitee, zoho_inventory, shopify, dynamics365, d2lbrightspace, salesforce, brightpearl, okta, clockify, jira, blackboard, confluence, share_point, workable, bamboohr, borneo, gorgias, zoho, kommo, netsuite, salesforce_service_cloud, datadog, salesforce_marketing_cloud, mailchimp, accelo ```

Some are intentionally per-connection — Salesforce's `instance_url` is per-user-in-Salesforce (Mercury re-fetches it via `/services/oauth2/userinfo` at runtime); Pipedrive re-derives `companyDomain` from the OAuth token response's `api_domain`. Others (Jira/Confluence/SharePoint/Okta) are likely the same bug as Zendesk and worth fixing — but each needs a per-toolkit judgment call from someone with customer context. Not batching here to keep this reviewable.

Related (not in this PR)

The Modern Treasury "Invalid Authorization Request — Invalid scope" complaint is a separate issue that does NOT need a code change. Apollo already supports per-auth-config scope override via `apps/apollo/src/lib/connected_accounts/oAuth2.ts:164-186` `resolveScopesForAuthorizationUrl()`: if the auth config's `scopes` array is non-empty, those override the toolkit defaults. The fix is for the customer to edit the `scopes` field on their auth config (drop `webhooks:read`/`webhooks:write` if their Zendesk plan doesn't support the Webhooks API). I declined to ship a PR for this since the platform behavior is already correct.

How did I test this PR

`make validate-config file=apps/zendesk/config.ts` — ✅ type checking passed, config validates.
`make validate-config file=apps/gong/config.ts` — ✅ type checking passed, config validates.
Initial CI run flagged `check_config_breaking_changes.py` (which is correct — see the migration concern above). Added the documented `# ci-skip` comment with a reason pointing to this PR.
Codex review: ✅ no findings — "The changes are mostly formatting, with the substantive field-type updates for Gong and Zendesk appearing consistent with the intended auth-config behavior. I did not identify a discrete regression that would block the patch."
Reviewer to verify in staging before merge: (a) create a fresh Zendesk auth config, enter the subdomain once, then have a second user connect through that same auth config and confirm the subdomain prompt does not appear. (b) Take an EXISTING Zendesk auth config and try to create a new connection under it — observe whether Apollo errors, falls back, or asks for subdomain on the connection form. The answer to (b) determines whether the Apollo-side fallback / migration described above needs to ship before this is safe to merge.

🤖 Generated with Claude Code

@zen-agent1mo ago

Post-PR follow-up — all checks complete (with one important reviewer-action item)

Step	Result
`make validate-config apps/zendesk/config.ts`	✅ type checking passed, config validates
`make validate-config apps/gong/config.ts`	✅ type checking passed, config validates
Codex review (1 iteration)	✅ no findings
GitHub Actions CI	9 passed / 0 failed / 2 pending (`checks`, `lint-and-type-checks` finishing in background)
Testing checklist	See note below

Testing checklist note

This is a metadata flip on a `.ts` config — the runtime behavior change happens in Apollo's field routing, not Mercury. Mercury has no unit-test target for this kind of metadata flow; the equivalent test coverage already exists in `packages/auth-config/src/tests/bearer_token_injection.test.ts:109` (Braintree-style `auth_config_field` baseUrl routing) and the platform-side change has been validated by Codex review + Mercury's strict-fields type validation.

End-to-end runtime verification cannot be done from this sandbox — it requires (a) staging Apollo deployment, (b) creating a fresh Zendesk OAuth client, (c) creating an auth config + connection through the dashboard. Flagged for reviewer action.

⚠️ Reviewer action items (in order of importance)

Verify the migration concern described in the PR description before merging — specifically: take an EXISTING Zendesk auth config in staging and try to create a new connection under it. Observe whether Apollo errors, falls back to per-connection prompt, or asks for subdomain on the connection form. The answer determines whether an Apollo-side fallback PR (or a one-time data migration) needs to ship before this is safe for prod.
Smoke-test the new flow: create a fresh Zendesk auth config (admin), enter subdomain once, then have a second user connect under the same auth config and confirm they don't see a subdomain prompt. Same for Gong.
Decide whether to expand to the 27 candidate toolkits flagged in the PR description (Jira, Confluence, SharePoint, Okta, BambooHR, etc.) — needs per-toolkit judgment from someone with customer context, not blanket batching.

loading diff…

@zen-agent1mo ago

Post-PR follow-up — all checks complete (with one important reviewer-action item)

Step	Result
`make validate-config apps/zendesk/config.ts`	✅ type checking passed, config validates
`make validate-config apps/gong/config.ts`	✅ type checking passed, config validates
Codex review (1 iteration)	✅ no findings
GitHub Actions CI	9 passed / 0 failed / 2 pending (`checks`, `lint-and-type-checks` finishing in background)
Testing checklist	See note below

Testing checklist note

⚠️ Reviewer action items (in order of importance)

Verify the migration concern described in the PR description before merging — specifically: take an EXISTING Zendesk auth config in staging and try to create a new connection under it. Observe whether Apollo errors, falls back to per-connection prompt, or asks for subdomain on the connection form. The answer determines whether an Apollo-side fallback PR (or a one-time data migration) needs to ship before this is safe for prod.
Smoke-test the new flow: create a fresh Zendesk auth config (admin), enter subdomain once, then have a second user connect under the same auth config and confirm they don't see a subdomain prompt. Same for Gong.
Decide whether to expand to the 27 candidate toolkits flagged in the PR description (Jira, Confluence, SharePoint, Okta, BambooHR, etc.) — needs per-toolkit judgment from someone with customer context, not blanket batching.