Skip to main content
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

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.
User status mapping. Lumos derives account status from a user’s account memberships across your organizations. 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

​
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.