Migrating from Legacy DocuSign Authentication to JWT Grant

What's Changing and Why

DocuSign is discontinuing Basic Auth (username/password) authentication for all eSignature API integrations. This is a security upgrade on DocuSign's end — they are requiring all partners to use OAuth 2.0.

If your ContractSafe organization currently has a shared DocuSign username and password configured under Settings → Security & Integrations → DocuSign Settings, your integration uses the legacy method that is being retired.

Who Is Affected

This change affects your organization if both of the following are true:

• Your ContractSafe account has a DocuSign Default User and DocuSign Default Password configured in organization settings.
• You have not yet set up JWT Grant authentication (Integration Key, Service Account User UUID, and RSA Private Key).

If your organization is already using JWT Grant or if each user authenticates individually with their own DocuSign account, no action is needed.

Your Options

How to Set Up JWT Grant Authentication

This is a one-time configuration performed by an administrator. You will need admin access to both ContractSafe and DocuSign.

Prerequisites

• A ContractSafe account with administrator privileges
• A DocuSign account with administrator privileges
• Access to the DocuSign eSignature admin portal

Step 1: Create a DocuSign Integration App

1. Log in to the DocuSign eSignature admin portal.
2. In the left sidebar, go to Integrations → Apps and Keys.
3. Click Add App and Integration Key.
4. Give the app a name (e.g., ContractSafe Integration) and click Create App.
5. Note the Integration Key (Client ID) — you will need this later.

Step 2: Generate an RSA Key Pair

Still on the app detail page:

1. Scroll to the Authentication section.
2. Under Service Integration (JWT Grant), click Generate RSA.
3. DocuSign will display a private key and a public key — this is the only time the private key is shown.
4. Copy or download the private key immediately and store it securely. It will look like:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA...
-----END RSA PRIVATE KEY-----

The public key is saved automatically in DocuSign. You do not need to store it separately.

Step 3: Create or Identify a Service Account User

This is the DocuSign account that ContractSafe will impersonate. All envelopes sent through the integration will appear in this user's Drafts folder.

If you already have an existing account you'd like to use (such as the account currently configured as your DocuSign Default User), skip to step 4.

1. In the DocuSign admin portal, go to Users.
2. Click Add User and create a dedicated service account:
   • Name: Something descriptive, e.g., ContractSafe Integration
   • Email: A real, accessible email address (e.g., docusign-integration@yourcompany.com) — DocuSign will send a verification email
   • Permission Profile: Assign at minimum the DocuSign Sender permission profile
3. Complete email verification for the new user account.
4. Note the service user's API Username (User ID / GUID):
   • Go to Users, find the service account, and click on it
   • Copy the User UUID

Step 4: Grant Consent for the Integration

The service user must explicitly grant your integration permission to impersonate it. There are two ways to do this:

Option A: Admin Consent (requires Org Admin / Access Management feature)

If your DocuSign account has the Access Management feature and has claimed your email domain:

1. In the admin portal, go to Settings → Connected Apps.
2. Find your app and grant admin consent for the signature and impersonation scopes on behalf of your domain users.
3. No individual user action is required.

Option B: Individual Consent URL

If Org Admin is not available, construct a consent URL and have the service account user visit it while logged in to DocuSign:

https://account.docusign.com/oauth/auth
  ?response_type=code
  &scope=signature%20impersonation
  &client_id=YOUR_INTEGRATION_KEY
  &redirect_uri=https://www.docusign.com

Replace YOUR_INTEGRATION_KEY with the Integration Key from Step 1. The user clicks Allow Access and consent is recorded.

To verify consent was granted, log in as the service account user, go to Manage Profile → Connected Apps, and confirm your app appears there.

Step 5: Configure ContractSafe

1. Log in to ContractSafe as an administrator.
2. Navigate to Settings → Security & Integrations → DocuSign Settings.
3. Enter the following values:

Step 6: Test the Integration

1. Log in to ContractSafe as a non-admin user.
2. Open a contract and use the Send to DocuSign action.
3. Log in to the service account's DocuSign account at app.docusign.com.
4. Navigate to Manage → Drafts. The envelope should appear here, centralized under the service account.
5. Confirm the envelope can be sent from DocuSign as normal.

Optional: Individual User Override

Individual users can opt out of the organization-level JWT integration and route their sends through their own DocuSign account instead. When the override is enabled, ContractSafe will prompt that user to log in via OAuth, and their envelopes will land in their personal Drafts folder rather than the organization's service account.

This is configured per user in Personal Settings → Connections → DocuSign Settings.

What Happens If You Don't Migrate by March 31

If March 31 passes before you complete the JWT Grant setup:

• The stored DocuSign username and password will stop working.
• ContractSafe will automatically fall back to individual user OAuth authentication.
• Each user will be prompted to log in with their own DocuSign account the next time they try to send a document.
• Envelopes will go to each user's personal Drafts folder instead of a centralized location.

This is not permanent. You can complete the JWT Grant setup at any time after March 31 to restore the centralized workflow. Once configured, all users will immediately return to the shared service account experience.

Frequently Asked Questions