Docusign

DocuSign Integration Guide

This guide covers the DocuSign integration in Stack AI: connecting via JWT Grant, the available actions and triggers, and the Go-Live process to promote your integration key from DocuSign demo to production.

---

Actions

Action	Purpose
list_envelopes	List envelopes filtered by status, folder, template, or date range
get_envelope	Fetch a single envelope by ID
download_document	Download a signed/unsigned document or the certificate of completion (returns a Stack-AI signed URL)
send_envelope_from_template	Send a new envelope using a DocuSign template
void_envelope	Cancel/void an in-flight envelope
get_recipient_status	Get signing status of recipients on an envelope
list_templates	List available DocuSign templates
get_template_roles	Get role definitions on a template (so you know which roles/tabs to fill in)
get_tab_values	Get the values of form tabs/fields a recipient filled in

Triggers

Trigger	Fires when
on_envelope_status_change	An envelope's top-level status changes (e.g., sent → completed)
on_recipient_completed	A specific recipient finishes signing

Both triggers support an optional template_id filter so you only poll envelopes created from a specific template.

---

Why JWT Grant

JWT Bearer Grant is one of three OAuth 2.0 flows DocuSign supports for REST API access. Unlike Authorization Code Grant (which requires a user to sign in interactively), JWT Grant lets your integration mint access tokens server-side using:

• Your Integration Key (client ID)

• A user ID to impersonate

• An RSA private key

This is ideal for:

• Unattended workflows (cron, scheduled flows, multi-step automations)

• Server-to-server integrations

• Production deployments where humans shouldn't be in the auth loop

Reference: JWT Grant Authentication

---

Prerequisites

• A DocuSign developer account — sign up at developers.docusign.com.

• Admin access to that account (you'll need to create an Integration Key and upload an RSA keypair).

• A user in that account whose actions the integration will perform (you can use yourself).

• A developer account is different from your regular docusign account, but you will need it to establish a connection.

---

Connecting via JWT — step by step

Estimated time: 10–15 minutes end-to-end.

Step 1 — Create the Integration Key in DocuSign Developer

1. Sign in to admindemo.docusign.com (or admin.docusign.com if you're past Go-Live).

2. Navigate to Settings → Integrations → Apps and Keys.

3. Click Add App and Integration Key.

4. Give the app a clear name (e.g., Stack AI – Workflows).

5. After creation, you'll see the Integration Key GUID — copy it; you'll paste it into Stack AI later.

Reference: Apps and Keys / Integration Keys

Step 2 — Configure the Integration Key

On the Integration Key detail page in DocuSign Admin:

1. Under Authentication, select Authorization Code Grant.

   • This is required for the one-time consent flow (Step 4) even when your runtime uses JWT Grant.

2. Under Additional settings → Redirect URIs, click Add URI and enter StackAI's redirect URI: https://www.stackai.com/auth

3. Scroll to Service Integration → Add RSA Keypair.

   • DocuSign shows the public and private keys once. Download the private key file immediately and store it securely.

   • If you lose the private key, you'll need to generate a new pair.

The private key file looks like this:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA...
... many lines ...
-----END RSA PRIVATE KEY-----

You'll paste the entire contents (including the BEGIN/END lines) into Stack AI.

Step 3 — Find your Account ID, User ID, and Base URI

Still in the DocuSign Admin Console:

Field	Where to find it
Account ID	Apps and Keys → sidebar My Account Information → API Account ID
Base URI	Same sidebar → Account Base URI (e.g., https://demo.docusign.net or https://na3.docusign.net)
User ID	Users and Groups → Users → select the user → copy API Username

Copy all three.

Step 4 — Grant consent (one-time, per impersonated user)

JWT Grant requires that the user being impersonated has explicitly consented to the integration. Without this, every token mint will fail with consent_required.

1. In your browser, open a URL like the one below, replacing {INTEGRATION_KEY} and {REDIRECT_URI} with values from Steps 1 and 2:

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id={INTEGRATION_KEY}&redirect_uri={REDIRECT_URI}

   For production (after Go-Live), use account.docusign.com instead of account-d.docusign.com.

2. Sign in as the user you want to impersonate (the same one whose API Username you copied in Step 3).

3. Click Allow when DocuSign asks for consent.

4. You'll be redirected to {REDIRECT_URI}?code=.... The redirect destination doesn't have to work — consent is recorded on DocuSign's side the moment you click Allow.

Reference: Granting Consent

Step 5 — Create the connection in Stack AI

1. Open the New Connection dialog.

2. Select DocuSign (JWT) from the provider list.

3. Fill in the form:

   Field	Value
   Integration Key	from Step 1
   User ID	from Step 3
   RSA Private Key	full PEM contents from Step 2 (paste into the multiline field)
   Account ID	from Step 3
   Base URI	from Step 3 — e.g., https://demo.docusign.net for sandbox

4. Click Create Connection.

Stack AI will:

• Sign a JWT with your private key

• Exchange it for an access token at https://account-d.docusign.com/oauth/token (or account.docusign.com for production)

• Call /oauth/userinfo and verify that your configured account_id is among the accounts the token can access, and that the base_uri matches that account's base_uri

If anything is misconfigured you'll get a specific error message — see Troubleshooting.

---

Promoting your integration key to production (Go-Live)

DocuSign integration keys are environment-scoped. The key you created in your developer account works only against the demo environment. To use it against a production DocuSign account, you must go through DocuSign's Go-Live review.

Reference (official): Go-Live Process

Step 1 — Build and test in demo

Make sure your integration is fully working against demo. Run real workflows end-to-end. Treat this as your acceptance phase.

Step 2 — Meet the API call requirement

DocuSign requires at least 20 successful, distinct API calls against your integration key in demo before they will approve Go-Live. Stack AI workflow runs count — each action invocation issues one or more requests.

You can verify the count in the DocuSign Developer Console under Apps and Keys → [your app] → API Requests.

Step 3 — Submit for Go-Live review

1. In the Developer Console, open your integration key.

2. Open the Actions menu (top right of the integration detail page) → Start Go-Live Review.

3. Fill out the questionnaire. The questions are usually:

   • Description of your integration.

   • Which DocuSign features and API endpoints you use (envelopes, templates, webhooks, etc.).

   • Expected production traffic volume.

   • How you handle errors and rate limits.

   • Authentication method — answer "OAuth v2 for REST" (JWT Bearer Grant specifically). We do not use App Passwords / SOAP.

4. Submit.

DocuSign typically responds within a few business days. Common reasons for rejection are inefficient polling, missing error handling, or unclear scope — none of which should be issues for the Stack AI integration as long as you configure triggers with template filters where applicable and avoid excessive polling frequency.

Reference: Go-Live Review Process

Step 4 — Promote the Integration Key to your production account

Once approved:

1. Log into your production DocuSign account at docusign.com (separate from your developer account — even if the email is the same, the accounts are different).

2. Go to Settings → Integrations → Apps and Keys.

3. Click Add an Application via Integration Key.

4. Enter the same integration key GUID from Step 1 of the JWT setup. The key is now valid in both demo and production.

5. Re-add your redirect URIs and RSA public key in the production app — these do not automatically carry over from demo.

Step 5 — Re-grant consent in production

Production consent is separate from demo consent. Re-run the consent URL against the production auth server (note the host change):

https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id={INTEGRATION_KEY}&redirect_uri={REDIRECT_URI}

Sign in as the production user you want to impersonate and click Allow.

---

Switching a Stack AI workflow to production

After Go-Live and re-consent, create a new connection in Stack AI:

Field	Production value
Integration Key	same GUID (it works in both environments after promotion)
User ID	your production API Username (not the demo one)
RSA Private Key	same private key file you generated in demo
Account ID	your production API Account ID
Base URI	your production base URI — e.g. https://na3.docusign.net, https://eu.docusign.net (region-specific; find it in the production Admin Console under Apps and Keys → My Account Information)

Update each workflow node that uses DocuSign to use the new production connection. Keep the demo connection around for testing.

---

Troubleshooting

Error / symptom	Cause	Fix
consent_required	The impersonated user hasn't granted consent for this integration key in this environment	Re-run the consent URL (Step 4 of JWT setup; use the matching environment)
invalid_grant	Wrong User ID, or the user is in a different DocuSign account than the integration key	Verify the User ID was copied from the same DocuSign account that owns the integration key
"Failed to load RSA private key"	Pasted only a fragment of the key, mixed up public/private, or the key is encrypted	Paste the full contents (including -----BEGIN/-----END lines) of the private key file. DocuSign keypairs are unencrypted PEM
Account {id} is not accessible from this token (health check)	The Account ID you entered isn't one your token can act on	Verify the Account ID matches the same DocuSign account as the integration key and user
Configured base URI {x} does not match the account's base URI {y}	Wrong base URI for the account (very common after Go-Live — production accounts are region-specific)	Copy the exact Base URI from the Admin Console you're using; for production it varies (na1/na2/na3/eu/...)
Trigger missing events / firing late	Polling cron interval, or template filter too narrow	Check the trigger's config; the template_id filter (if set) means only envelopes from that exact template are polled

---

Reference: DocuSign docs

• JWT Grant Authentication overview

• JWT consent flow

• JWT token generator (manual testing)

• Apps and Keys / Integration Keys

• Go-Live overview

• Go-Live review process

• eSignature REST API reference