feat(credentials): DocuSign JWT Grant credentials next to OAuth

A saved DocuSign credential that authenticates with JWT Grant (an
integration key, an impersonated user ID, the app's RSA private key, and an
environment), offered as a second option beside the existing OAuth
connection, which is unchanged.

The minter signs an RS256 assertion (iss = integration key, sub = user,
aud = the environment's authentication host without a scheme, scope
"signature impersonation"), exchanges it at that host's /oauth/token, then
reads /oauth/userinfo on the same host to bind the pinned account (or the
user's default) and returns its eSignature REST base. Both hosts come only
from the stored environment; a base_uri outside that environment's
docusign.net shape is never trusted with the token. GUIDs and the key are
checked before any request, and tokens are re-minted about 15 minutes
before they expire, as DocuSign advises.

DocuSign tools take the account base as an authoritative credential param,
so a caller can never supply it, and DocuSignClient skips its
deployment-host userinfo lookup when one is bound. OAuth tokens resolve
exactly as before.

Save-time failures map to consent_required (the connect modal shows the
exact consent URL for the key and environment) and account_not_found (a
pinned account the user does not belong to), alongside the shared
invalid_credentials and provider_unavailable codes.

Author: waleedlatif1

apps/docs/content/docs/integrations/docusign-service-account.mdx

@@ -0,0 +1,88 @@
+---
+title: DocuSign JWT Grant
+description: Connect DocuSign to Sim with an integration key and RSA keypair that acts as one DocuSign user, instead of a personal OAuth connection
+---
+
+import { Callout } from '@/components/ui/callout'
+import { Step, Steps } from '@/components/ui/steps'
+
+Connect DocuSign with JWT Grant when a workflow should keep working without anyone signing in again. Sim signs a short-lived assertion with your app's RSA private key, exchanges it for an access token that acts as one DocuSign user, and repeats that every hour. DocuSign issues no refresh token for JWT Grant, so nothing expires as long as the key and the user's consent stay in place.
+
+Every envelope, template, and download runs as the impersonated user, with that user's DocuSign permissions. Use a dedicated user when you can.
+
+## Prerequisites
+
+- A DocuSign account in the environment you want: a free developer account (demo) or a production account
+- Admin access to **Apps and Keys** in that account, to create the integration key
+
+## Create the integration key [#creating-the-integration-key]
+
+<Steps>
+  <Step>
+    In DocuSign, open the **Apps and Keys** page and add an app. Give it a name (e.g. `Sim workflows`) and click **ADD**
+  </Step>
+  <Step>
+    Copy the integration key DocuSign assigns (a GUID)
+  </Step>
+  <Step>
+    Under **RSA key pair**, click **GENERATE RSA**. Copy the private key before you close the dialog, including its `BEGIN` and `END` lines. DocuSign masks it afterwards and can't show it again
+  </Step>
+  <Step>
+    Under **Redirect URI**, click **ADD URI** and enter the address you open Sim at (for example `https://sim.ai`). DocuSign requires a redirect URI for the consent step; Sim never uses what it receives there
+  </Step>
+  <Step>
+    Leave **User Application** set to **Yes** (the default) and click **SAVE**
+  </Step>
+</Steps>
+
+<Callout type="warn">
+The private key lets anyone holding it act as any user who has consented to this integration key. Sim encrypts it at rest and never shows it again. Treat it like a password.
+</Callout>
+
+## Find the user ID [#finding-the-user-id]
+
+The **Apps and Keys** page shows your **User ID** and **API Account ID**, both GUIDs. To act as a different user, use that user's ID instead. Use the user ID, not an email address.
+
+The account ID is optional. Sim uses the user's default account unless you enter one, so you only need it when the user belongs to more than one account.
+
+## Add the credential to Sim [#adding-the-credential-to-sim]
+
+<Steps>
+  <Step>
+    Open **Integrations** from your workspace sidebar
+  </Step>
+  <Step>
+    Search for "DocuSign" and open it, then click **Add to Sim** and choose **Add JWT Grant app**
+  </Step>
+  <Step>
+    Choose the **Environment** the integration key was created in: **Developer (demo)** or **Production**. A key that hasn't gone live only works in the developer environment
+  </Step>
+  <Step>
+    Paste the integration key, the impersonated user ID, the RSA private key, and optionally the account ID
+  </Step>
+  <Step>
+    Click **Add JWT Grant app**. Sim requests a token and reads the user's accounts once to check everything matches
+  </Step>
+</Steps>
+
+## Grant consent [#granting-consent]
+
+DocuSign won't issue tokens for a user until that user (or an organization admin) consents to the integration key. The first time you add the credential, Sim shows an error with the exact consent link for your integration key and environment. Open the link signed in as the impersonated user and click **Accept**. DocuSign then redirects to the redirect URI you added; the page it lands on doesn't matter, so close it and add the credential again.
+
+You only need to consent once per user and integration key, unless the user revokes it.
+
+## Use the credential in workflows [#using-the-credential-in-workflows]
+
+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.
+
+## Fix connection errors
+
+| Error | What to check |
+| ----- | ------------- |
+| Needs the impersonated user's consent | Open the consent link from the error signed in as that user, accept, and add the credential again. Consent can also be revoked later, which stops runs until it is granted again |
+| Couldn't authenticate | The integration key, user ID, and private key must belong to the same app, in the environment you chose. A key created in the developer environment isn't valid in production until it goes live. A private key from a deleted keypair no longer works |
+| User isn't a member of the account | The account ID you entered isn't one the user belongs to. Check it, or leave it blank |
+
+To rotate the key, generate a new RSA keypair on the integration key, reconnect the credential in Sim with the new private key, test a workflow, then delete the old keypair. DocuSign allows up to five keypairs per integration key. See [DocuSign's JWT Grant documentation](https://developers.docusign.com/platform/auth/jwt/jwt-get-token/).

apps/docs/content/docs/integrations/docusign.mdx

@@ -11,8 +11,12 @@ import { ReferenceDetails } from "@/components/ui/reference-details"
 
 {/* MANUAL-CONTENT-START:intro */}
 Use [DocuSign](https://www.docusign.com) to send envelopes for e-signature, create them from templates, inspect recipients and signing status, and download completed documents. Pending envelopes can be voided with a reason.
+
+Connect a DocuSign account through OAuth, or an integration key that acts as one user through [JWT Grant](/integrations/docusign-service-account).
 {/* MANUAL-CONTENT-END */}
 
+Connection guides: [JWT Grant](/integrations/docusign-service-account).
+
 ## OAuth scopes [#oauth-scopes]
 
 Sim requests these scopes when someone connects a DocuSign account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

apps/docs/content/docs/integrations/meta.json

@@ -66,6 +66,7 @@
     "devin",
     "discord",
     "docusign",
+    "docusign-service-account",
     "downdetector",
     "dropbox",
     "dropcontact",

apps/docs/content/integration-navigation.json

@@ -38,6 +38,10 @@
       "integration": "databricks",
       "title": "Databricks connections"
     },
+    "docusign-service-account": {
+      "integration": "docusign",
+      "title": "JWT Grant"
+    },
     "google-service-account": {
       "title": "Google service accounts"
     },

apps/sim/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal/client-credential-account-modal.tsx

@@ -35,6 +35,8 @@ import {
 
 const logger = createLogger('ClientCredentialAccountModal')
 
+type FieldValues = Partial<Record<ClientCredentialAccountFieldId, string>>
+
 const FALLBACK_ERROR_MESSAGE = "We couldn't save this credential. Try again in a moment."
 
 /**
@@ -46,6 +48,7 @@ function messageForClientCredentialError(
   err: unknown,
   descriptor: ClientCredentialAccountDescriptor,
   requiredFields: ClientCredentialAccountField[],
+  values: FieldValues,
   fallbackMessage = FALLBACK_ERROR_MESSAGE
 ): string {
   if (isApiClientError(err) && err.code) {
@@ -66,6 +69,18 @@ function messageForClientCredentialError(
       }
       case 'provider_unavailable':
         return `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.`
+      }
+      case 'account_not_found': {
+        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.`
+      }
       case 'duplicate_display_name':
         return 'A credential with that name already exists in this workspace.'
       default:
@@ -75,8 +90,6 @@ function messageForClientCredentialError(
   return fallbackMessage
 }
 
-type FieldValues = Partial<Record<ClientCredentialAccountFieldId, string>>
-
 function openDocs(url: string): void {
   window.open(url, '_blank', 'noopener,noreferrer')
 }
@@ -242,6 +255,7 @@ function ClientCredentialAccountModalForm({
           err,
           descriptor,
           required,
+          values,
           onSubmitCredentials ? getErrorMessage(err, FALLBACK_ERROR_MESSAGE) : undefined
         )
       )

apps/sim/lib/credentials/client-credential-accounts/descriptors.ts

@@ -105,6 +105,16 @@ export interface ClientCredentialAccountDescriptor {
   defaultAuthMethod?: string
   /** Sim setup guide, docked bottom-left of the connect modal. */
   docsUrl: string
+  /**
+   * Builds the provider's one-time consent URL from the values in the connect
+   * modal, for providers whose grant fails with `consent_required` until a user
+   * approves the app (DocuSign JWT Grant). `redirectUri` is the Sim origin the
+   * modal is open on. Returns `undefined` when the values can't form one.
+   */
+  consentUrl?: (
+    values: Partial<Record<ClientCredentialAccountFieldId, string>>,
+    redirectUri: string
+  ) => string | undefined
   /**
    * Optional one-line caveat, rendered under the `orgId` field of the connect modal. A descriptor
    * without an `orgId` field puts its guidance in a field `hint` instead.
@@ -125,6 +135,7 @@ export const ORACLE_FUSION_SERVICE_ACCOUNT_PROVIDER_ID = 'oracle-fusion-service-
 export const GREENHOUSE_SERVICE_ACCOUNT_PROVIDER_ID = 'greenhouse-service-account' as const
 export const JAMA_SERVICE_ACCOUNT_PROVIDER_ID = 'jama-service-account' as const
 export const HELPSCOUT_SERVICE_ACCOUNT_PROVIDER_ID = 'helpscout-service-account' as const
+export const DOCUSIGN_SERVICE_ACCOUNT_PROVIDER_ID = 'docusign-service-account' as const
 
 /** Permissions requested when connecting a Manage Vanta application. */
 export const VANTA_PERMISSION_OPTIONS = [
@@ -150,6 +161,7 @@ export type ClientCredentialAccountProviderId =
   | typeof GREENHOUSE_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof HELPSCOUT_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof JAMA_SERVICE_ACCOUNT_PROVIDER_ID
+  | typeof DOCUSIGN_SERVICE_ACCOUNT_PROVIDER_ID
 
 /**
  * Exact account-specific SuiteTalk origin accepted by NetSuite's OAuth and
@@ -385,6 +397,63 @@ export function resolveZohoDeskDataCenter(rawDataCenter?: string): {
   return { id, ...ZOHO_DESK_DATA_CENTERS[id] }
 }
 
+/**
+ * DocuSign's two account systems. Each environment has its own authentication
+ * service and its own eSignature REST hosts, and a token from one is never
+ * accepted by the other, so the credential stores which one it belongs to and
+ * nothing a caller types can change it.
+ * @see https://developers.docusign.com/platform/auth/jwt/jwt-get-token/
+ */
+export const DOCUSIGN_ENVIRONMENTS = {
+  demo: { authHost: 'account-d.docusign.com', label: 'Developer (demo)' },
+  production: { authHost: 'account.docusign.com', label: 'Production' },
+} as const satisfies Record<string, { authHost: string; label: string }>
+
+export type DocuSignEnvironment = keyof typeof DOCUSIGN_ENVIRONMENTS
+
+/** Resolves a stored environment value, or `undefined` when it is not exactly one of the two. */
+export function resolveDocuSignEnvironment(
+  value: string | undefined
+): DocuSignEnvironment | undefined {
+  const trimmed = value?.trim()
+  return trimmed && Object.hasOwn(DOCUSIGN_ENVIRONMENTS, trimmed)
+    ? (trimmed as DocuSignEnvironment)
+    : undefined
+}
+
+/** DocuSign integration keys, user IDs, and account IDs are all GUIDs. */
+export const DOCUSIGN_GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** An unencrypted PEM RSA private key, in the PKCS#1 form DocuSign generates or PKCS#8. */
+const DOCUSIGN_PRIVATE_KEY_REGEX =
+  /^-----BEGIN (RSA )?PRIVATE KEY-----[\s\S]+-----END (RSA )?PRIVATE KEY-----$/
+
+/** Scopes a JWT Grant credential requests; `impersonation` is what JWT consent covers. */
+export const DOCUSIGN_JWT_SCOPES = 'signature impersonation'
+
+/**
+ * The one-time consent URL the impersonated user opens to let the integration
+ * key act as them. DocuSign requires a `redirect_uri` registered on the key;
+ * the JWT flow ignores the `code` it receives.
+ * @see https://developers.docusign.com/platform/auth/jwt/jwt-get-token/
+ */
+function buildDocuSignConsentUrl(
+  integrationKey: string,
+  environment: string | undefined,
+  redirectUri: string
+): string | undefined {
+  const resolved = resolveDocuSignEnvironment(environment)
+  const key = integrationKey.trim()
+  if (!resolved || !DOCUSIGN_GUID_REGEX.test(key)) return undefined
+  const params = new URLSearchParams({
+    response_type: 'code',
+    scope: DOCUSIGN_JWT_SCOPES,
+    client_id: key,
+    redirect_uri: redirectUri,
+  })
+  return `https://${DOCUSIGN_ENVIRONMENTS[resolved].authHost}/oauth/auth?${params.toString()}`
+}
+
 export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
   ClientCredentialAccountProviderId,
   ClientCredentialAccountDescriptor
@@ -417,6 +486,69 @@ export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
     helpText:
       'Create API credentials in your Jama profile. Your account needs REST API access and a Named Creator license.',
   },
+  [DOCUSIGN_SERVICE_ACCOUNT_PROVIDER_ID]: {
+    providerId: DOCUSIGN_SERVICE_ACCOUNT_PROVIDER_ID,
+    serviceLabel: 'DocuSign',
+    connectNoun: 'JWT Grant app',
+    fields: [
+      {
+        id: 'dataCenter',
+        label: 'Environment',
+        placeholder: 'Select an environment',
+        secret: false,
+        options: (Object.keys(DOCUSIGN_ENVIRONMENTS) as DocuSignEnvironment[]).map((id) => ({
+          value: id,
+          label: DOCUSIGN_ENVIRONMENTS[id].label,
+        })),
+        hint: 'Where the integration key was created. Keys start in the developer environment until they go live.',
+      },
+      {
+        id: 'clientId',
+        label: 'Integration key',
+        placeholder: '00000000-0000-0000-0000-000000000000',
+        secret: false,
+        hintPattern: DOCUSIGN_GUID_REGEX,
+        hintNormalize: (value) => value.trim(),
+        hintMessage: 'Expected the integration key GUID from Apps and Keys.',
+      },
+      {
+        id: 'username',
+        label: 'Impersonated user ID',
+        placeholder: '00000000-0000-0000-0000-000000000000',
+        secret: false,
+        hintPattern: DOCUSIGN_GUID_REGEX,
+        hintNormalize: (value) => value.trim(),
+        hintMessage: 'Expected the User ID GUID from Apps and Keys, not an email address.',
+        hint: 'Every call runs as this user, with their DocuSign permissions.',
+      },
+      {
+        id: 'privateKey',
+        label: 'RSA private key',
+        placeholder: '-----BEGIN RSA PRIVATE KEY-----',
+        secret: true,
+        multiline: true,
+        hintPattern: DOCUSIGN_PRIVATE_KEY_REGEX,
+        hintNormalize: (value) => value.trim(),
+        hintMessage:
+          'Expected the full PEM private key from the RSA keypair, including its BEGIN and END lines.',
+      },
+      {
+        id: 'orgId',
+        label: 'Account ID',
+        placeholder: "Defaults to the user's default account",
+        secret: false,
+        optional: true,
+        hintPattern: DOCUSIGN_GUID_REGEX,
+        hintNormalize: (value) => value.trim(),
+        hintMessage: 'Expected the API Account ID GUID from Apps and Keys.',
+      },
+    ],
+    docsUrl: 'https://docs.sim.ai/integrations/docusign-service-account',
+    helpText:
+      "Only needed when the user belongs to more than one account and the one to use isn't their default.",
+    consentUrl: (values, redirectUri) =>
+      buildDocuSignConsentUrl(values.clientId ?? '', values.dataCenter, redirectUri),
+  },
   [RAMP_SERVICE_ACCOUNT_PROVIDER_ID]: {
     providerId: RAMP_SERVICE_ACCOUNT_PROVIDER_ID,
     serviceLabel: 'Ramp',