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

# DocuSign integration

> Shared setup and authentication reference for the DocuSign tools.

Shared setup and authentication reference for the DocuSign tools. Per-tool docs:

* [docusign\_send\_envelope](/docs/tools/docusign-send-envelope)
* [docusign\_get\_envelope](/docs/tools/docusign-get-envelope)
* [docusign\_get\_envelope\_form\_data](/docs/tools/docusign-get-envelope-form-data)

## Authentication — JWT Grant, not authorization code

DocuSign is connected with **JWT Grant** (server-to-server), not the authorization-code flow used by the OAuth connectors.

Two reasons this is not a stylistic choice:

* An unattended agent has nobody to click through a consent screen when a token goes stale.
* DocuSign's authorization-code **refresh tokens expire after 30 days**. A long-running agent on that flow would silently stop sending envelopes roughly every month — surfacing as "patients stopped getting forms", days after the cause.

Under JWT Grant the platform signs a fresh assertion with the app's RSA key whenever the cached access token nears expiry. There is no refresh token to rot. The one human step is a **single one-time admin consent** when the integration is first set up.

## Configuration

| Field             | Required | Where to find it                                                                                             |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `integration_key` | yes      | DocuSign Admin → Apps and Keys → your app (this is the client id)                                            |
| `user_id`         | yes      | Admin → Users → the user → **API Username** (a GUID, not an email)                                           |
| `private_key`     | yes      | The RSA private key generated under Apps and Keys, PEM including BEGIN/END lines. DocuSign shows it **once** |
| `account_id`      | no       | Admin → Account → Account ID. Only needed when the user can reach more than one account                      |
| `environment`     | no       | `demo` (default) or `prod`                                                                                   |

`environment` **fails safe**: anything that isn't exactly `prod` (case- and whitespace-insensitive) resolves to the demo sandbox, so a typo can never point a test integration at live, billable envelopes.

Saving the integration performs a real JWT grant and reads `/oauth/userinfo`, so a key that parses but was never consented — or an account the user cannot reach — fails at setup rather than at the first envelope send.

## One-time consent

If the grant returns `consent_required`, an administrator must grant consent once:

```
https://account-d.docusign.com/oauth/auth
  ?response_type=code
  &scope=signature%20impersonation
  &client_id=<integration_key>
  &redirect_uri=<a redirect URI registered on the app>
```

(Use `account.docusign.com` for production.) The tools surface this case with an explicit message naming the fix rather than the raw OAuth payload.

## Account base URI

The REST host differs per account (`na3`, `eu`, …), so it is discovered from `/oauth/userinfo` on first use and cached — never hardcoded to `demo.docusign.net`.

## Not covered yet

* **Downloading the signed PDF.** Retrieving envelope documents and filing them into a system of record needs the platform's file-storage plumbing, and pairs with an EHR upload tool that doesn't exist yet.
* **Connect webhooks.** Envelope lifecycle events (opened, completed) currently require polling `docusign_get_envelope`.
* **Voiding or correcting** an in-flight envelope.