> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/docusign-integration-setup.md).

# Docusign Integration Setup

### Getting Started

Use this guide to connect Docusign to your BalkanID tenant. You will need administrator access to your Docusign account and access to the Integrations section in BalkanID.

BalkanID authenticates to Docusign using JWT Grant, acting on behalf of a single Docusign user that you nominate. BalkanID recommends nominating a dedicated service account for this integration rather than a personal or employee-named account, so that the connection survives staff changes.

Once connected, BalkanID syncs your Docusign users, permission profiles, groups, folders and templates, along with the access between them.

{% hint style="warning" %}
The DocuSign integration currently fetches data for one account per integration. If the connected user belongs to multiple DocuSign accounts and a specific account is not selected, the integration automatically defaults to the user's primary account as configured in DocuSign.

**Note**: If this default account changes in DocuSign—either manually or because the user was removed from the account—the data synced to the integration will change accordingly.
{% endhint %}

#### Requirements:

Before you begin, collect the following values from Docusign:

* **Integration Key**
* **Impersonated User ID**
* **RSA Private Key**
* **Authentication Server**
* **Account ID** — only needed if the nominated user belongs to more than one Docusign account

### Configure Docusign within your BalkanID tenant

{% hint style="info" %}
Docusign requires all applications to be created in a demo or sandbox environment first; you cannot create an app directly in production. If you do not plan to test the integration in the demo environment, you can complete initial setup steps 1 and 2 below, then immediately skip to step 10 to promote your app to production.
{% endhint %}

1. Log in to your Docusign demo environment at `account-d.docusign.com` using an administrator account and navigate to **Admin** > **Apps and Keys**.
2. Under the My Apps / Integration Keys section, select **Add App and Integration Key**, provide a recognizable name for your application, and create it.
3. In the Additional Settings section, generate an RSA key pair. Copy the private key and store it securely immediately. Docusign will only display this key once; if you close the dialog before saving it, you will need to generate a new one.
4. On the same settings page, select Add URI. Docusign will not grant administrative consent without a registered redirect URI. However, BalkanID does not receive or use this redirect, so you can enter a placeholder value such as `https://localhost`.
5. Return to the main Apps and Keys page and copy the User ID of the account you want BalkanID to act as (this is your Impersonated User ID). If you need to nominate a different user, go to Settings > Users, open that user's profile, and copy their User ID instead.
6. Construct the consent URL by copying the following link and replacing `<YOUR_INTEGRATION_KEY>` and `<YOUR_REDIRECT_URI>` with the exact values from your application. Save this constructed URL. You will need to update and reuse it when setting up the production environment.

```
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation%20user_read%20group_read%20permission_read%20account_read&client_id=<YOUR_INTEGRATION_KEY>&redirect_uri=<YOUR_REDIRECT_URI>
```

7. Open your customized URL in a web browser. Sign in as the nominated impersonated user, then select Accept.
8. After you click Accept, your browser will attempt to load the placeholder redirect URI and display an error indicating the page cannot be loaded. This is expected behavior. You can safely close the tab, as Docusign has successfully stored the one-time consent.
9. To test the integration in the dev environment before promoting to production, proceed to step 13.
10. Promote your application from the demo environment to production. Promoting creates a brand-new app entry and does not carry over the RSA key pair or the redirect URI from the demo environment.
11. Once the app is live in production, open its settings. You must add the redirect URI again and generate a new RSA key pair. The demo private key will not work with the production integration key, so ensure you update the `docusign-private-key` in your BalkanID configuration.
12. Grant production consent by repeating the consent URL step for the production app. Ensure you use the production integration key, the production redirect URI, and the production Docusign endpoint (`account.docusign.com` instead of `account-d.docusign.com`) in the URL.
13. In BalkanID, head to **Integrations** > **Add integration**.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FfIP4uZQepHT6ABZT2YzW%2Fdocusign-add-integration.png?alt=media" alt="The BalkanID Integrations page, with the Add integration button at the top right of the Connected Applications tab"><figcaption><p>Integrations page</p></figcaption></figure></div>

8. Search for **Docusign**, select it, and click **Next**.
9. Set up the **Primary application owner** (mandatory) and the **Description**, if any. Set up **Secondary application owner(s)**, if any.
10. Under **Select Extraction Type**, choose **Direct Configuration** and enter the values you collected. Leave **Authentication Server** set to `account.docusign.com` unless your account is in the Docusign developer environment, in which case use `account-d.docusign.com`. Leave **Account ID** empty unless the nominated user belongs to more than one Docusign account.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2F6CufwomKGuKeKxDMqkyA%2Fdocusign-direct-configuration.png?alt=media" alt="The Direct Configuration fields for Docusign: Integration Key, Impersonated User ID, RSA Private Key, Authentication Server and Account ID"><figcaption><p>Direct Configuration</p></figcaption></figure></div>

11. Click Next to move onto Optional Configuration.
12. Fill **Optional Configuration**, if required.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FZbipc8nl8LTFl5YsVIaj%2Foptional-configuration.png?alt=media" alt="The Optional Configuration step, showing Reviewer Settings on the left and Select Fulfillment options on the right"><figcaption><p>Optional Configuration</p></figcaption></figure></div>

13. Once you have filled in the information, click **Save**. Your integration is now configured and you will see the status of the integration displayed alongside other integrations on the Integrations page. When data is available, the integration Status column will read **Connected** and the integration Message will read **Data available**.

### Integration Scopes

| Read Only Scopes                                                                                                                                                           | Lifecycle Management Scopes |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **`user_read`** — read access to users                                                                                                                                     | N/A                         |
| **`group_read`** — read access to groups                                                                                                                                   | N/A                         |
| **`permission_read`** — read access to permission profiles                                                                                                                 | N/A                         |
| **`account_read`** — read access to account information                                                                                                                    | N/A                         |
| **`signature`** and **`impersonation`** — required by Docusign to issue an access token on behalf of the nominated user. BalkanID does not create, send or sign envelopes. | N/A                         |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/docusign-integration-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
