About Docusign
Docusign is an electronic signature and agreement management platform. Connecting Docusign to Serval lets your workflows send envelopes for signature, track their status, read completed agreements, and manage templates across your Docusign account.What the Docusign integration enables
| Capability | Description |
|---|---|
| Send envelopes | Create and send envelopes for signature — single documents or multi-recipient routing |
| Track envelope status | Query envelope state (sent, delivered, completed, declined, voided) and status timestamps |
| Read recipients and tabs | List signers, CC recipients, and signing field data on an envelope |
| Use templates | List and send from pre-built Docusign templates with role-based recipients |
| Account metadata | Read account name, plan, and settings for the connected Docusign account |
Prerequisites
- A Docusign developer account (free, sign up at developers.docusign.com)
- Admin permissions on that developer account (required to create apps)
- A Docusign app with an Integration Key (Client ID) and Secret Key (Client Secret)
Serval uses Docusign’s Authorization Code Grant flow. You need an account that can securely store a client secret — this is the default for Serval’s server-side integration. Do not enable PKCE; PKCE is only required for apps that cannot store a secret (SPAs, native mobile).
Docusign Configuration
Before connecting in Serval, create a Docusign app in the developer sandbox and configure it for OAuth 2.0. You will connect Serval to it using the Demo environment. When you are ready to use it against real Docusign accounts, follow Promoting your app to Production below.Create a Docusign app in the developer sandbox
- Sign in to your developer account at apps-d.docusign.com/admin/apps-and-keys
- Click Add App and Integration Key
- Enter an app name (for example,
Serval) — this is what users see on the Docusign consent screen - Docusign generates an Integration Key. Copy it — this is your Client ID. Keep the page open for the next steps
Set the integration type
Under Integration Type, select Private custom integration.
Serval treats each customer’s Docusign app as a private, per-organization app — your Integration Key never leaves your Docusign tenant. Do not pick Public integration or Embedded integration; those are for very different distribution models.
Configure the User Application authentication
Scroll to the Authentication section, inside the User Application block, and click through in this order:
- “Is your application able to securely store a client secret?” → click Yes
- Authentication Method for your App — auto-selects Authorization Code Grant. No action needed
- Require Proof Key for Code Exchange (PKCE) — leave this unchecked. Serval stores the client secret server-side so PKCE is unnecessary and Docusign will reject your callback if the checkbox is on but Serval is not sending a PKCE verifier
- Under Secret Keys, click + Add Secret Key
- Docusign reveals the new Secret Key one time only. Copy it immediately — this is your Client Secret. Store it in a password manager
Skip Service Integration (RSA keypairs)
Leave the Service Integration section alone. Do not click Generate RSA or Upload RSA.
RSA keypairs are only used for Docusign’s JWT Grant flow, which is a different authentication model Serval does not use today. Generating a keypair here does nothing for the Serval integration.
Add the Serval Redirect URI
Open a new tab, go to Serval → Apps → Available → Docusign → Connect. The modal shows a Redirect URI with a copy button. Copy it.Back in Docusign, still on the same app configuration page:
- Scroll to Additional Settings → Redirect URIs
- Click + Add URI
- Paste the Redirect URI from Serval (for example,
https://svflow-auth-config.api.serval.com/docusign/oauth/callback) - Click Save
Skip CORS configuration
Leave CORS Configuration empty — do not add any Origin URLs or Allowed HTTP Methods. Serval calls the Docusign API server-to-server, never from a browser, so CORS allow-listing is not required.
Settings recap
After saving, your Docusign app should match this:| Section | Setting | Value |
|---|---|---|
| General Info | App Name | Your choice (e.g. Serval) |
| General Info | Integration Key | auto-generated — copy as 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 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 Docusign to Serval
Fill in the connection form
In the Connect Docusign dialog:
- Copy the Redirect URI at the top and make sure it is added to your Docusign app’s Redirect URIs list (see the previous section)
- Select the Environment:
- Production — your app lives at
apps.docusign.com - Demo — your app lives at
apps-d.docusign.com(developer sandbox)
- Production — your app lives at
- Enter the Integration Key (Client ID) from your Docusign app
- Enter the Secret Key (Client Secret) you generated
- Click Connect to Docusign
Authorize in Docusign
You will be redirected to Docusign’s consent page.
- Sign in to the Docusign account whose data you want Serval to work against
- Review the requested permissions (
signature,extended) and click Allow - You will be redirected back to Serval with the integration connected
OAuth Scopes Requested
Serval requests only these scopes during the Authorization Code flow:| Scope | Purpose |
|---|---|
signature | Read and manage envelopes, recipients, templates, and documents |
extended | Issue a refresh token so the connection stays alive without re-consenting hourly |
impersonation (that scope is only used for the JWT Grant flow, which Serval does not use).
Regional Base URIs
Docusign serves the eSignature REST API from region-specific data centers (for example,na4.docusign.net, eu.docusign.net, au.docusign.net, demo.docusign.net). Serval detects your account’s base URI automatically during the OAuth flow — there is nothing to configure. All API calls from Serval workflows go to the correct region for the connected account.
Promoting your app to Production
Once you have tested everything against a Docusign developer sandbox, use Docusign’s Go-Live process to migrate the app into production. Summary:Pass the Go-Live API call requirements
Docusign requires at least 20 successful, distinct API calls from your Integration Key against the developer sandbox before Go-Live eligibility. Running a few real Serval workflows (send envelope, fetch status, list templates, etc.) will accumulate these automatically.
Submit the app for review
In the developer sandbox admin, open your app and click Actions → Start Review. Docusign will validate your API-call history and then allow you to promote the app.
Promote the Integration Key to Production
Follow Docusign’s on-screen prompts to migrate the Integration Key into each production data center you need (
www.docusign.net, eu.docusign.net, etc.).Add the production Redirect URI and generate a new Secret Key
In the production apps.docusign.com/admin/apps-and-keys, re-enter the Redirect URI, and generate a new Secret Key. Production uses different secrets from the sandbox.
Reconnect Serval using the Production environment
In Serval, disconnect the Demo-connected Docusign integration and reconnect — this time selecting Production as the environment. Paste the production Integration Key and production Secret Key. Serval will redirect the user to
account.docusign.com (instead of account-d.docusign.com) and capture the production base_uri / account_id.Troubleshooting
Connected to the wrong account
If your Docusign user has access to multiple accounts, Serval connects to the one you chose during the Docusign consent screen. To switch, disconnect and reconnect, then pick a different account at consent time.