> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docusign

> Connect your own Docusign OAuth app to Serval so workflows can send, track, and manage e-signature envelopes on demand.

## About Docusign

Docusign is an electronic signature and agreement management platform. Serval connects to a single Docusign account using a Docusign app that you create and own - you paste your app's Integration Key and Secret Key into the connect modal, approve access on Docusign's consent screen, and Serval binds the connection to your default Docusign account. Workflows can then read and write Docusign data on demand. The integration currently carries a **Beta** badge in Serval's Apps list.

**Authentication:** OAuth 2.0 Authorization Code grant with a customer-supplied (bring-your-own) Docusign app, against either the Production or Demo environment.

**Data sync:** On-demand only. There is no background sync, no webhooks, and no entity ingestion - Docusign is contacted only when a workflow step runs the "Docusign API request" action.

## What the Docusign integration enables

| Capability                  | Description                                                                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Read account information    | Look up the connected account's name, billing plan, suspension status, and (optionally) full account settings.                                               |
| List envelopes              | Find envelopes by date range, status, sender email, or folder, with sorting and paged results - keep paging until no next page is reported.                  |
| Create and send envelopes   | Send documents for signature with signers and carbon-copy recipients in a routing order, or send from a saved template; send immediately or save as a draft. |
| Read and update an envelope | Check an envelope's status, subject, and timestamps, update it, or re-send it to recipients.                                                                 |
| Read envelope recipients    | See signers and carbon copies, their routing order, and optionally their signing fields and extended details.                                                |
| List and search templates   | Browse and search templates by text or folder to drive template-based sends.                                                                                 |

All of this runs through a single typed workflow action, "Docusign API request", whose schema covers the endpoints above. Anything defined in the [Docusign API](https://developers.docusign.com/docs/esign-rest-api/reference/) can be accessed through Serval.

## Get your credentials

You need a Docusign app configured for the Authorization Code grant, with one Secret Key and Serval's Redirect URI registered. Docusign only lets you create new apps in a developer (sandbox) account - production use requires promoting the app through Docusign's Go-Live process. Full provider documentation: [Authorization Code Grant (Docusign docs)](https://developers.docusign.com/platform/auth/authcode/).

<Note>
  If the Production admin page shows "You cannot create an integration key in production", that is expected - create the app in a [developer account](https://developers.docusign.com/platform/account/) first, then promote it later via [Go-Live](https://developers.docusign.com/platform/go-live/).
</Note>

<Steps>
  <Step title="Open the Docusign Apps and Keys admin page">
    Sign in at the [Demo / developer sandbox admin page](https://apps-d.docusign.com/admin/apps-and-keys) for a developer account, or the [Production admin page](https://apps.docusign.com/admin/apps-and-keys) for a promoted production app.
  </Step>

  <Step title="Create the app and copy the Integration Key">
    Click **Add App and Integration Key** and enter an app name (for example, Serval) - this is what users see on the Docusign consent screen. Copy the auto-generated **Integration Key**; this is your Client ID.
  </Step>

  <Step title="Set the Integration Type">
    Under **Integration Type**, select **Private custom integration**. Do not pick Public or Embedded integration - those are for very different distribution models, and your Integration Key never leaves your Docusign tenant.
  </Step>

  <Step title="Configure authentication">
    In the **Authentication** section's User Application block, answer **Yes** to "Is your application able to securely store a client secret?" (this auto-selects Authorization Code Grant), and leave **Require Proof Key for Code Exchange (PKCE)** unchecked.
  </Step>

  <Step title="Generate a Secret Key">
    Under **Secret Keys**, click **+ Add Secret Key**. Copy it immediately; this is your Client Secret. If you lose it, generate a new one and reconnect Serval.
  </Step>

  <Step title="Skip the Service Integration section">
    Do not generate or upload RSA keypairs. Those are for Docusign's JWT Grant flow, which Serval does not use - generating a keypair here does nothing for the Serval integration.
  </Step>

  <Step title="Register Serval's Redirect URI">
    In Serval, open **Apps > Available > Docusign > Connect** and copy the **Redirect URI** shown at the top of the modal. In Docusign, go to **Additional Settings > Redirect URIs > + Add URI** and paste it exactly.
  </Step>

  <Step title="Save the app">
    Leave **CORS Configuration** empty (Serval calls Docusign server-to-server), then click **Save** at the bottom of the page - selections do not persist without saving.
  </Step>
</Steps>

<Warning>
  Docusign reveals each Secret Key one time only, and the Redirect URI must match exactly - any difference in scheme, host, path, or trailing slash makes Docusign reject the OAuth callback with a "redirect\_uri\_mismatch" error.
</Warning>

### Settings recap

After saving, your Docusign app should match this:

| Section             | Setting                           | Value                                               |
| ------------------- | --------------------------------- | --------------------------------------------------- |
| General Info        | App Name                          | Your choice (for example, Serval)                   |
| General Info        | Integration Key                   | Auto-generated - copy as your Client ID             |
| -                   | Integration Type                  | **Private custom integration**                      |
| Authentication      | Can securely store client secret? | **Yes**                                             |
| Authentication      | Authentication Method             | Authorization Code Grant                            |
| Authentication      | Require PKCE                      | **Unchecked**                                       |
| Authentication      | Secret Keys                       | One added - copy as your Client Secret              |
| Service Integration | RSA Keypairs                      | None - leave empty                                  |
| Additional Settings | Redirect URIs                     | One entry - the URI shown in Serval's connect modal |
| Additional Settings | CORS Configuration                | Empty - no origins, no methods                      |

## Connect in Serval

<Steps>
  <Step title="Open the connect modal">
    Go to **Apps > Available > Docusign** and click **Connect**. The "Connect Docusign" modal opens; its intro text links straight to the Docusign Apps and Keys admin pages if you still need to create the app.
  </Step>

  <Step title="Copy the Redirect URI">
    The **Redirect URI** field at the top is read-only with a **Copy** button (it reads "Copied" for a moment after clicking). Helper text: "Add this as a Redirect URI in your Docusign app's Additional Settings section." Make sure this exact value is registered in your Docusign app before continuing.
  </Step>

  <Step title="Choose the Environment">
    Pick **Production** or **Demo**; the default is Production. Helper text: "Choose Production if your Docusign app was created at apps.docusign.com, or Demo if it was created in a developer account at apps-d.docusign.com."
  </Step>

  <Step title="Enter your Integration Key (Client ID) (required)">
    Text field with placeholder "Paste your Docusign Integration Key". Surrounding whitespace is trimmed before the value is submitted.
  </Step>

  <Step title="Enter your Secret Key (Client Secret) (required)">
    Password field with placeholder "Paste your Docusign Secret Key". Also trimmed of surrounding whitespace before submission.
  </Step>

  <Step title="Click Connect to Docusign">
    The button stays disabled until both key fields are filled in (whitespace-only values count as blank). It reads "Connecting..." while submitting, then your browser is sent to Docusign's sign-in and consent screen. Approve access, and Serval completes the connection - it is bound to your default Docusign account and named after that account.
  </Step>
</Steps>

<Note>
  Complete the Docusign consent step within 10 minutes of clicking **Connect to Docusign** - the submitted credentials are held only that long before the flow expires.
</Note>

There is no in-place credential editing for this integration. To rotate the Secret Key or change any setting, reconnect through the full flow; reconnecting from the existing Docusign app instance updates the same connection rather than creating a duplicate.

## Verifying the connection

The Docusign integration ships one health check:

* **Test Docusign Connection** - asks Docusign for the connected account's details using the stored connection, verifying Serval can authenticate and reach your account.
  * Success: `Successfully connected to Docusign account "[name]".` (if Docusign does not return an account name, the message says "your account" instead)
  * Failure: `Unable to reach Docusign. Verify the OAuth credentials are valid and the account has not been deactivated.`

<Tip>
  If the test is green but workflows touch the wrong envelopes or templates, the connection may be bound to the consenting user's default Docusign account rather than the one you intended. Reconnect and choose the correct account on Docusign's consent screen.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Environment is fixed at connect time and silently defaults to Production">
    Production apps (apps.docusign.com) and Demo apps (apps-d.docusign.com) authenticate against different Docusign hosts. Serval treats any Environment value other than Demo - including blank - as Production, so picking the wrong option means your keys simply will not validate. Match the Environment to where the app was created.
  </Accordion>

  <Accordion title="Do not enable PKCE; skip RSA keypairs and JWT Grant">
    Serval runs a plain Authorization Code exchange, so a Docusign app with **Require PKCE** checked will reject the callback. RSA keypairs, the JWT Grant flow, and the impersonation scope are not used anywhere - Serval requests exactly the signature and extended scopes (extended is what makes Docusign issue a refresh token, so the connection stays alive without re-consenting hourly). See the [OAuth scopes reference](https://developers.docusign.com/platform/auth/reference/scopes/).
  </Accordion>

  <Accordion title="Consent must finish within 10 minutes">
    The credentials you submit are cached for only 10 minutes between starting the flow and Docusign redirecting back. Taking longer surfaces "Invalid or expired OAuth state" or "OAuth session expired, please try again" - re-open the connect modal and start again.
  </Accordion>

  <Accordion title="Rotating, regenerating, or revoking the Secret Key requires reconnecting">
    There is no update-credentials form for Docusign. If you regenerate the Secret Key in Docusign (or the app's consent is revoked on the Docusign side), token refresh starts failing and the health check goes red. A connect attempt with a wrong or regenerated Secret Key fails at Docusign's token exchange - Docusign reports an "invalid\_grant" error and Serval shows "Failed to exchange authorization code". Reconnect through the full connect flow with the new key; reconnecting from the existing app instance updates the connection in place.
  </Accordion>

  <Accordion title="Serval connects to the user's default Docusign account">
    After consent, Serval binds the connection to the consenting user's default account (or the first account returned) and names it after that account - or after the account ID if Docusign returns no name. If the user has no accounts, connecting fails with "No Docusign accounts found for this user"; an account missing its API address fails with "Docusign did not return an API base URL for the account". To target a different account, reconnect and pick it at consent time.
  </Accordion>

  <Accordion title="Production use requires Docusign Go-Live promotion">
    Docusign only allows app creation in developer accounts. Before promoting, the Integration Key needs at least 20 successful, distinct API calls against the developer sandbox (running real Serval workflows accumulates these). Then, in the developer sandbox admin, open the app and use **Actions > Start Review** - Docusign validates your API-call history and lets you promote the Integration Key into each production data center you need via [Go-Live](https://developers.docusign.com/platform/go-live/). Production uses a different Secret Key than the sandbox - after promoting, re-register the Redirect URI, generate a new production Secret Key, and reconnect Serval with Environment set to Production.
  </Accordion>

  <Accordion title="Bring-your-own app - credentials live in your tenant">
    Serval does not ship a shared Docusign OAuth app. You supply your own app's Integration Key and Secret Key at connect time; Serval stores them with the connection and reuses them for automatic token refresh. Each connection is bound to one Docusign app and one account.
  </Accordion>

  <Accordion title="Regional API address is discovered automatically">
    Docusign serves its API from region-specific data centers (for example, na4.docusign.net, eu.docusign.net, or demo.docusign.net for Demo accounts). Serval captures your account's home data center during the connect flow and routes all workflow calls there automatically - there is nothing to configure. Workflow traffic from Serval only ever goes to hosts under docusign.net.
  </Accordion>

  <Accordion title="The integration is in Beta">
    Docusign appears with a Beta badge in Serval's Apps list. Behavior may evolve faster than for generally available integrations.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Docusign integration.