> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/workflow-builder/apps/docusign.md).

# 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](https://developers.docusign.com/platform/auth/jwt/)

***

### Prerequisites

* A DocuSign **developer account** — sign up at [developers.docusign.com](https://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**](https://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](https://developers.docusign.com/platform/build-integration/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](https://developers.docusign.com/platform/auth/jwt/jwt-grant-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](https://developers.docusign.com/platform/go-live/)

#### 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](https://developers.docusign.com/platform/go-live/go-live-process/)

#### Step 4 — Promote the Integration Key to your production account

Once approved:

1. Log into your **production** DocuSign account at [docusign.com](https://www.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](https://developers.docusign.com/platform/auth/jwt/)
* [JWT consent flow](https://developers.docusign.com/platform/auth/jwt/jwt-grant-consent/)
* [JWT token generator (manual testing)](https://developers.docusign.com/platform/auth/jwt/jwt-get-token/)
* [Apps and Keys / Integration Keys](https://developers.docusign.com/platform/build-integration/integration-keys/)
* [Go-Live overview](https://developers.docusign.com/platform/go-live/)
* [Go-Live review process](https://developers.docusign.com/platform/go-live/go-live-process/)
* [eSignature REST API reference](https://developers.docusign.com/docs/esign-rest-api/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stackai.com/workflow-builder/apps/docusign.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.