Skip to main content

​
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

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 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).
If the Production admin page shows “You cannot create an integration key in production”, that is expected - create the app in a developer account first, then promote it later via Go-Live.
1

Open the Docusign Apps and Keys admin page

Sign in at the Demo / developer sandbox admin page for a developer account, or the Production admin page for a promoted production app.
2

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.
3

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.
4

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.
5

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.
6

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.
7

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.
8

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.
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.

​
Settings recap

After saving, your Docusign app should match this:

​
Connect in Serval

1

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.
2

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.
3

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.”
4

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.
5

Enter your Secret Key (Client Secret) (required)

Password field with placeholder “Paste your Docusign Secret Key”. Also trimmed of surrounding whitespace before submission.
6

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.
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.
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.
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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. 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.
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.
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.
Docusign appears with a Beta badge in Serval’s Apps list. Behavior may evolve faster than for generally available integrations.
Need help? Contact support@serval.com for assistance with your Docusign integration.