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

# DocuSign

*This article covers DocuSign connections created after February 2026. To check your version, look at the Domain ID under your domain. If it shows `docusign_ics`, use the steps below. If it shows `docusign.com`, use the legacy connector instructions.*

## After this article

You'll be able to connect DocuSign to Lumos to sync and provision access to users, groups, and permission profiles.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User account records. For provisioning, the membership status is set to `PENDING` and the user gets an email to activate their account. |
| Groups | Permission | Yes | Yes | Access groups. Lumos can assign and unassign group membership |
| Permission Profiles | Permission | Yes | Yes | Permission profiles. Lumos can assign a profile but not unassign one (see below) |

**Provisioning behavior:**

* **Create:** requires a username, an email, and a permission profile chosen at creation time. Lumos creates the user in the connected DocuSign account with that profile. DocuSign sets the membership to `activation_sent` and emails the user to activate their account, so the account shows as Pending in Lumos until they do.
* **Assign a permission profile:** a DocuSign user has exactly one permission profile, so assigning a new one replaces the current one. If DocuSign links the profile to a group (the Admin profile and Admin group, for example), the user joins that group automatically.
* **Assign or unassign a group:** Lumos adds and removes group memberships in the connected account. Every user belongs to DocuSign's built-in `Everyone` group, which can't be removed.
* **Unassign a permission profile:** not supported. DocuSign has no API to remove a profile without replacing it, and profile IDs differ per organization, so Lumos can't safely pick a least-privilege replacement. Change profiles by assigning a different one.
* **Reactivate:** Lumos checks the user's membership in the connected account first. If it's already active, nothing is sent. Otherwise Lumos re-sends the activation for that membership. This works on the connected account only.

| Deprovisioning Action | Type | Description |
| - | - | - |
| Deactivate | User | Closes the user's memberships in every account where membership isn't already closed. Organization Admins are protected and can't be deactivated this way. |

**User status mapping.** Lumos derives account status from a user's account memberships across your organizations.

| DocuSign membership state | Lumos Account Status |
| - | - |
| At least one `active` account membership | Active |
| No `active` accounts, at least one `activation_sent` | Access Created |
| No `active` or `activation_sent`, at least one `activation_required` | Staged |
| Only `closed` or `disabled` memberships | Deprovisioned |

**Entitlements.** Lumos retrieves the user's **Role**, which is their permission profile in the DocuSign organization, such as DocuSign Sender or DocuSign Viewer.

**Last activity.** Lumos derives last activity from `usageHistory`, comparing `lastSentDateTime` and `lastSignedDateTime` and taking the later timestamp. For inactive users these fields are absent, so no activity is returned.

## Required plan and roles

* **DocuSign plan:** your organization needs the **DocuSign Admin** product to connect this integration.
* **DocuSign role:** the connecting user must be at least a **Users Administrator**. For the connector to list users, groups, and permission profiles and to manage memberships, authenticate as an **Organization Admin** or equivalent.
* To confirm you have DocuSign Admin, log into DocuSign, click the dialpad in the upper left, click **Admin**, and check that you can see the **Users** tile. If you can't see the **Admin** tab or **Users** tile, ask your DocuSign admin. Your subscription must include the Admin product.
* **OAuth scopes** requested during connection:
  * `extended` (required): keeps data refreshed with a longer-living refresh token (30 days)
  * `organization_read` (required): read organization lists and data
  * `user_read` (required): read user data
  * `user_write` (required): create, update, or delete users
  * `account_read` (required): read account data

## Read-only access vs provisioning

**Is read-only possible?** No. All five OAuth scopes requested during connection, including `user_write`, are required to connect.

**What full provisioning requires.** The connecting user needs at least Users Administrator, and authenticating as an Organization Admin (or equivalent) is needed for the connector to list users, groups, and permission profiles and manage memberships. Your organization also needs the DocuSign Admin product. Follow the steps below to create the OAuth app and complete the consent flow as an Organization Admin.

**Watch out for.** Organization Admins are protected in DocuSign and can't be deprovisioned through the API, attempts to deprovision them from Lumos will fail and you'll need to remove them directly in the DocuSign console instead. Also note this article covers connections on the `docusign_ics` Domain ID, created after February 2026. If your Domain ID shows `docusign.com`, you're on the legacy connector and should use its separate instructions.

## Instructions

**Phase 1: Create a DocuSign OAuth application**

1. Log in to DocuSign Admin and go to **Admin → Accounts → Integrations → Apps and Keys → Add App and Integration Key**.
2. Name your app and create it.
3. After you create the app, the **Integration Key** appears below the App Name field. This is your **Client ID**. Store it for later.
4. Set the **Integration Type** to **Third-party integration key**.
5. In the **Authentication** section, click **Add Secret Key** and store the generated value. This is your **Client Secret**.
6. In **Additional settings**, click **Add URI** and paste `https://app.lumosidentity.com/integrations/ics_oauth2_callback`.
7. Click **Save**.

**Phase 2: Gather your Organization ID and Account ID**

1. For the **Organization ID**, open the DocuSign Admin dashboard, click **Organization** in the left menu, then **Features → Organization Details**. Your Organization ID is shown there. If you don't see the Organization menu, create an Organization first.
2. For the **Account ID**, open the DocuSign Admin dashboard, click **Accounts**, select your account, then scroll to **Integrations → Apps and Keys**. The account ID is under **My Account Information → API account ID**.

**Phase 3: Connect in Lumos**

1. Enter the **Client ID**, **Client Secret**, **Organization ID**, and **Account ID**.
2. Set the **Sandbox / Demo** option. Use Demo (sandbox) while testing. For production, promote the app or create it in production and leave the sandbox option off. It defaults to production.
3. Click **Connect** and complete the OAuth consent flow in DocuSign as the Organization Admin.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Can't connect the integration.** Your DocuSign plan must include the DocuSign Admin product, and your user must be an Organization Admin. If you hit an error before the DocuSign login screen, clear your browser cookies and try again.

**An Organization Admin can't be deprovisioned.** Organization Admins can't be deprovisioned through the DocuSign API. Remove them in the DocuSign console instead. Deprovision attempts in Lumos fail for these users.

**The consent flow completes but you get "failed to forward oauth callback from ics".** That message is generic, and the two causes worth checking first are both on the DocuSign side. After OAuth, Lumos validates your Organization ID and Account ID against DocuSign's list of organizations, which only returns organizations the signed-in user administers.

* **Level of Access is set to "Allow Some".** The connecting user can hold Organization Administrative Access and still be scoped to one segment of the organization, in which case DocuSign returns an empty organization list and validation fails. In DocuSign Admin, under **Organization → Administrators**, change that user's **Level of Access** from "Allow Some" to **"Allow All"**. The Users Administrator permission profile itself is fine, it is the access level that needs raising.
* **The wrong form of the Account ID was entered.** Lumos matches on the account's GUID-format **API account ID**, not the shorter numeric account number. Take it from DocuSign Admin → **Accounts** → select the account → **Integrations → Apps and Keys** → **My Account Information → API account ID**, and confirm the value you paste looks like a GUID.

Also confirm the Organization ID itself matches the value in **Organization → Features → Organization Details**. Reconnect after correcting either field.