@@ -75,7 +75,7 @@ You only need to consent once per user and integration key, unless the user revo
 
 Add a DocuSign block and select the saved credential in the account dropdown. Every DocuSign operation works with it the same way as with a connected account. Sim calls the eSignature REST API for the account it found when it last requested a token, in the environment stored on the credential.
 
-Knowledge base syncs from DocuSign look up the account through your deployment's DocuSign OAuth host and always use the user's default account. Use a JWT Grant credential there only when its environment matches the deployment's, and connect a personal account when you need a non-default account.
+Knowledge base syncs from DocuSign can use the credential too. They read the same account in the same environment, and envelope links open in that environment's DocuSign web app.
 
 ## Fix connection errors
 
 
@@ -9,6 +9,7 @@ import {
   ChipModalFooter,
   ChipModalHeader,
   ChipTextarea,
+  CopyCodeButton,
   SecretInput,
 } from '@sim/emcn'
 import { createLogger } from '@sim/logger'
@@ -37,6 +38,12 @@ const logger = createLogger('ClientCredentialAccountModal')
 
 type FieldValues = Partial<Record<ClientCredentialAccountFieldId, string>>
 
+/** Submit-error copy, with an optional provider link the user must open to recover. */
+interface ClientCredentialErrorCopy {
+  message: string
+  link?: { href: string; label: string }
+}
+
 const FALLBACK_ERROR_MESSAGE = "We couldn't save this credential. Try again in a moment."
 
 /**
@@ -50,44 +57,65 @@ function messageForClientCredentialError(
   requiredFields: ClientCredentialAccountField[],
   values: FieldValues,
   fallbackMessage = FALLBACK_ERROR_MESSAGE
-): string {
+): ClientCredentialErrorCopy {
   if (isApiClientError(err) && err.code) {
     // Names the fields the *selected* auth method needed, so a JWT failure
     // doesn't tell the user to check a consumer secret they never entered.
     const fieldLabels = requiredFields.map((field) => field.label).join(', ')
     switch (err.code) {
       case 'invalid_credentials':
-        return `We couldn't authenticate with those credentials. Check that the ${fieldLabels} all belong to the same ${descriptor.serviceLabel} app and that the app is authorized.`
+        return {
+          message: `We couldn't authenticate with those credentials. Check that the ${fieldLabels} all belong to the same ${descriptor.serviceLabel} app and that the app is authorized.`,
+        }
       case 'permission_conflict':
-        return 'Use the same permissions for connections to this application, or create a separate application for different permissions.'
+        return {
+          message:
+            'Use the same permissions for connections to this application, or create a separate application for different permissions.',
+        }
       case 'site_not_found': {
         // "host field" named a label no provider renders — Salesforce calls it
         // My Domain host, and Zoom/Box/Zoho Desk have no host field at all.
         const hostFieldLabel =
           descriptor.fields.find((field) => field.id === 'orgId')?.label ?? 'host'
-        return `We couldn't find a ${descriptor.serviceLabel} account at that host. Check the ${hostFieldLabel} field and try again.`
+        return {
+          message: `We couldn't find a ${descriptor.serviceLabel} account at that host. Check the ${hostFieldLabel} field and try again.`,
+        }
       }
       case 'provider_unavailable':
-        return `We couldn't reach ${descriptor.serviceLabel} to verify these credentials. Try again in a moment.`
+        return {
+          message: `We couldn't reach ${descriptor.serviceLabel} to verify these credentials. Try again in a moment.`,
+        }
       case 'consent_required': {
         const redirectUri = window.location.origin
         const consentUrl = descriptor.consentUrl?.(values, redirectUri)
         return consentUrl
-          ? `${descriptor.serviceLabel} needs the impersonated user's consent first. Add ${redirectUri} as a redirect URI on the integration key, open this link signed in as that user, accept, then try again: ${consentUrl}`
-          : `${descriptor.serviceLabel} needs the impersonated user's consent first. See the setup guide.`
+          ? {
+              message: `${descriptor.serviceLabel} needs the impersonated user's consent first. Add ${redirectUri} as a redirect URI on the integration key, then open the consent page signed in as that user, accept, and try again.`,
+              link: { href: consentUrl, label: 'Open consent page' },
+            }
+          : {
+              message: `${descriptor.serviceLabel} needs the impersonated user's consent first. See the setup guide.`,
+            }
       }
       case 'account_not_found': {
+        if (!values.orgId?.trim()) {
+          return {
+            message: `That user has no ${descriptor.serviceLabel} account in this environment. Check the environment and user ID.`,
+          }
+        }
         const accountFieldLabel =
           descriptor.fields.find((field) => field.id === 'orgId')?.label ?? 'account'
-        return `That user isn't a member of the ${accountFieldLabel} you entered. Check it, or leave it blank to use the user's default account.`
+        return {
+          message: `That user isn't a member of the ${accountFieldLabel} you entered. Check it, or leave it blank to use the user's default account.`,
+        }
       }
       case 'duplicate_display_name':
-        return 'A credential with that name already exists in this workspace.'
+        return { message: 'A credential with that name already exists in this workspace.' }
       default:
-        return fallbackMessage
+        return { message: fallbackMessage }
     }
   }
-  return fallbackMessage
+  return { message: fallbackMessage }
 }
 
 function openDocs(url: string): void {
@@ -155,7 +183,7 @@ function ClientCredentialAccountModalForm({
   const [values, setValues] = useState<FieldValues>({})
   const [displayName, setDisplayName] = useState(initialDisplayName ?? '')
   const [description, setDescription] = useState(initialDescription ?? '')
-  const [error, setError] = useState<string | null>(null)
+  const [error, setError] = useState<ClientCredentialErrorCopy | null>(null)
 
   const createCredential = useCreateScopedCredential()
   const updateCredential = useUpdateScopedCredential()
@@ -397,7 +425,26 @@ function ClientCredentialAccountModalForm({
           minHeight={80}
         />
 
-        <ChipModalError>{error}</ChipModalError>
+        <ChipModalError>
+          {error && (
+            <>
+              {error.message}
+              {error.link && (
+                <span className='mt-1 flex items-center gap-1'>
+                  <a
+                    href={error.link.href}
+                    target='_blank'
+                    rel='noopener noreferrer'
+                    className='text-[var(--brand-secondary)] underline underline-offset-2'
+                  >
+                    {error.link.label}
+                  </a>
+                  <CopyCodeButton code={error.link.href} />
+                </span>
+              )}
+            </>
+          )}
+        </ChipModalError>
       </ChipModalBody>
       <ChipModalFooter
         onCancel={() => onOpenChange(false)}
 
@@ -0,0 +1,98 @@
+import { knowledgeDocumentsUtilsMock } from '@sim/testing/mocks/knowledge-documents-utils.mock'
+import {
+  knowledgeSecureFetchMock,
+  knowledgeSecureFetchMockFns,
+} from '@sim/testing/mocks/knowledge-secure-fetch.mock'
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/knowledge/documents/utils', () => knowledgeDocumentsUtilsMock)
+vi.mock('@/lib/knowledge/documents/secure-fetch.server', () => knowledgeSecureFetchMock)
+
+import { docusignConnector } from '@/connectors/docusign/docusign'
+
+const mockFetchWithRetry = knowledgeSecureFetchMockFns.mockFetchWithRetry
+
+const DEFAULT_ACCOUNT = '99999999-0000-0000-0000-000000000001'
+const PINNED_ACCOUNT = '99999999-0000-0000-0000-000000000002'
+/** A production account, pinned, while the deployment's OAuth host stays on demo. */
+const BOUND_BASE = `https://na3.docusign.net/restapi/v2.1/accounts/${PINNED_ACCOUNT}`
+
+function reply(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+/** Answers userinfo with a demo default account and every envelope listing with one envelope. */
+function mockDocuSign() {
+  mockFetchWithRetry.mockImplementation(async (url: string) => {
+    if (url.endsWith('/oauth/userinfo')) {
+      return reply({
+        accounts: [
+          { account_id: DEFAULT_ACCOUNT, is_default: true, base_uri: 'https://demo.docusign.net' },
+        ],
+      })
+    }
+    return reply({
+      envelopes: [{ envelopeId: 'env-1', emailSubject: 'Offer', status: 'sent' }],
+      totalSetSize: '1',
+    })
+  })
+}
+
+describe('docusign connector account binding', () => {
+  it("lists the JWT credential's pinned account in its own environment, never the deployment default", async () => {
+    mockDocuSign()
+
+    const result = await docusignConnector.listDocuments('jwt-token', {}, undefined, {
+      credentialInstanceUrl: BOUND_BASE,
+    })
+
+    const urls = mockFetchWithRetry.mock.calls.map(([url]) => String(url))
+    expect(urls.some((url) => url.endsWith('/oauth/userinfo'))).toBe(false)
+    expect(urls[0].startsWith(`${BOUND_BASE}/envelopes?`)).toBe(true)
+    expect(result.documents[0]?.sourceUrl).toBe('https://app.docusign.com/documents/details/env-1')
+  })
+
+  it('resolves an OAuth token through userinfo on the deployment host as before', async () => {
+    mockDocuSign()
+
+    const result = await docusignConnector.listDocuments('oauth-token', {}, undefined, {})
+
+    const urls = mockFetchWithRetry.mock.calls.map(([url]) => String(url))
+    expect(urls[0]).toBe('https://account-d.docusign.com/oauth/userinfo')
+    expect(
+      urls[1].startsWith(`https://demo.docusign.net/restapi/v2.1/accounts/${DEFAULT_ACCOUNT}/`)
+    ).toBe(true)
+    expect(result.documents[0]?.sourceUrl).toBe(
+      'https://appdemo.docusign.com/documents/details/env-1'
+    )
+  })
+
+  it('validates a JWT credential without asking the deployment host', async () => {
+    mockDocuSign()
+
+    await expect(
+      docusignConnector.validateConfig('jwt-token', {}, { credentialInstanceUrl: BOUND_BASE })
+    ).resolves.toEqual({ valid: true })
+    expect(mockFetchWithRetry).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    'https://evil.example.com/restapi/v2.1/accounts/x',
+    `http://na3.docusign.net/restapi/v2.1/accounts/${PINNED_ACCOUNT}`,
+  ])('fails closed on a seeded account base of the wrong shape: %s', async (bound) => {
+    mockDocuSign()
+
+    await expect(
+      docusignConnector.listDocuments('jwt-token', {}, undefined, { credentialInstanceUrl: bound })
+    ).rejects.toThrow('DocuSign credential account URL is invalid')
+    await expect(
+      docusignConnector.validateConfig('jwt-token', {}, { credentialInstanceUrl: bound })
+    ).resolves.toMatchObject({ valid: false })
+    expect(mockFetchWithRetry).not.toHaveBeenCalled()
+  })
+})
@@ -2,7 +2,11 @@ import { createLogger } from '@sim/logger'
 import { getErrorMessage, toError } from '@sim/utils/errors'
 import { fetchWithRetry } from '@/lib/knowledge/documents/secure-fetch.server'
 import { VALIDATE_RETRY_OPTIONS } from '@/lib/knowledge/documents/utils'
-import { getDocusignOAuthUrl, getDocusignWebBase } from '@/lib/oauth/docusign'
+import {
+  getDocusignOAuthUrl,
+  getDocusignWebBase,
+  parseDocuSignAccountApiBase,
+} from '@/lib/oauth/docusign'
 import { docusignConnectorMeta } from '@/connectors/docusign/meta'
 import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
 import { parseTagDate } from '@/connectors/utils'
@@ -34,6 +38,8 @@ interface DocuSignUserInfo {
 interface ResolvedAccount {
   accountId: string
   baseUri: string
+  /** Web app origin for envelope links; set only for a credential-bound account. */
+  webBase?: string
 }
 
 interface DocuSignSigner {
@@ -138,6 +144,22 @@ function computeLookbackDays(
   return Math.min(incremental, baseline)
 }
 
+/**
+ * The account a JWT Grant credential is bound to, seeded into the sync context
+ * from its token. Its environment and pinned account come from the credential,
+ * so the deployment's OAuth host is never asked. A seeded value of the wrong
+ * shape fails the run rather than falling back to the user's default account.
+ */
+function credentialBoundAccount(
+  syncContext: Record<string, unknown> | undefined
+): ResolvedAccount | undefined {
+  const bound = syncContext?.credentialInstanceUrl
+  if (bound === undefined) return undefined
+  const account = parseDocuSignAccountApiBase(bound)
+  if (!account) throw new Error('DocuSign credential account URL is invalid')
+  return account
+}
+
 /**
  * Resolves and caches the user's DocuSign account ID and base URI in the sync context.
  * The userinfo lookup is expensive and identical across every page of a sync run, so it is
@@ -151,6 +173,11 @@ async function resolveAccount(
   const cacheKey = '_docusignAccount'
   const cached = syncContext?.[cacheKey] as ResolvedAccount | undefined
   if (cached) return cached
+  const bound = credentialBoundAccount(syncContext)
+  if (bound) {
+    if (syncContext) syncContext[cacheKey] = bound
+    return bound
+  }
 
   const response = await fetchWithRetry(
     getDocusignOAuthUrl('/oauth/userinfo'),
@@ -211,9 +238,12 @@ function buildContentHash(envelope: DocuSignEnvelope): string {
 /**
  * Builds a DocuSign web console link to the envelope, when an envelope ID is present.
  */
-function buildSourceUrl(envelopeId: string | undefined): string | undefined {
+function buildSourceUrl(
+  envelopeId: string | undefined,
+  account: ResolvedAccount
+): string | undefined {
   if (!envelopeId) return undefined
-  return `${getDocusignWebBase()}/documents/details/${envelopeId}`
+  return `${account.webBase ?? getDocusignWebBase()}/documents/details/${envelopeId}`
 }
 
 /**
@@ -286,14 +316,14 @@ function buildMetadata(envelope: DocuSignEnvelope): Record<string, unknown> {
  * Creates a lightweight document stub from an envelope list entry. No per-envelope API
  * calls are made — content is fetched lazily by getDocument for new/changed envelopes only.
  */
-function envelopeToStub(envelope: DocuSignEnvelope): ExternalDocument {
+function envelopeToStub(envelope: DocuSignEnvelope, account: ResolvedAccount): ExternalDocument {
   return {
     externalId: envelope.envelopeId ?? '',
     title: envelope.emailSubject?.trim() || 'Untitled DocuSign Envelope',
     content: '',
     contentDeferred: true,
     mimeType: 'text/plain',
-    sourceUrl: buildSourceUrl(envelope.envelopeId),
+    sourceUrl: buildSourceUrl(envelope.envelopeId, account),
     contentHash: buildContentHash(envelope),
     metadata: buildMetadata(envelope),
   }
@@ -505,7 +535,7 @@ export const docusignConnector: ConnectorConfig = {
      */
     let capped = envelopes.length < rawEnvelopes.length
 
-    let documents = envelopes.map(envelopeToStub)
+    let documents = envelopes.map((envelope) => envelopeToStub(envelope, account))
     if (documents.length > remaining) {
       documents = documents.slice(0, remaining)
       capped = true
@@ -597,7 +627,7 @@ export const docusignConnector: ConnectorConfig = {
         content,
         contentDeferred: false,
         mimeType: 'text/plain',
-        sourceUrl: buildSourceUrl(envelope.envelopeId),
+        sourceUrl: buildSourceUrl(envelope.envelopeId, account),
         contentHash: buildContentHash(envelope),
         metadata: buildMetadata(envelope),
       }
@@ -618,15 +648,18 @@ export const docusignConnector: ConnectorConfig = {
 
   validateConfig: async (
     accessToken: string,
-    sourceConfig: Record<string, unknown>
+    sourceConfig: Record<string, unknown>,
+    syncContext?: Record<string, unknown>
   ): Promise<{ valid: boolean; error?: string }> => {
     const maxEnvelopes = sourceConfig.maxEnvelopes as string | undefined
     if (maxEnvelopes && (Number.isNaN(Number(maxEnvelopes)) || Number(maxEnvelopes) < 0)) {
       return { valid: false, error: 'Max envelopes must be a non-negative number' }
     }
 
     try {
-      await resolveAccount(accessToken, undefined, VALIDATE_RETRY_OPTIONS)
+      if (!credentialBoundAccount(syncContext)) {
+        await resolveAccount(accessToken, undefined, VALIDATE_RETRY_OPTIONS)
+      }
       return { valid: true }
     } catch (error) {
       const message = getErrorMessage(error, 'Failed to validate configuration')