DocuSign API calls using legacy username/password authentication will fail worldwide from March 2023
To continue calling DocuSign APIs after this date, you must login to your DocuSign account as an administrator and make changes to enable OAuth in your Integration Apps. You must then grant one-time consent to allow ongoing OAuth authentication for your DocuSign API user. You can continue to use your existing API user once you grant this consent to them.
You must do this for all your development and production DocuSign accounts.
You must also install the latest DocuSign Exchange package into your Journey Manager, and change your DocuSign Service Connection settings to match the changes made in your DocuSign accounts.
In summary, you must:
- Configure OAuth authentication in your DocuSign accounts
- Grant one-time consent to your DocuSign API user(s)
- Install the latest DocuSign Exchange component
- Configure Journey Manager DocuSign Service Connection settings
Follow these steps to configure OAuth authentication in your DocuSign account:
- Login to your DocuSign account as an admin user you want to use to make API calls, you can use the link in the form below
- Click the Settings tab to visit your Admin Dashboard page, then navigate to the Apps and Keys page
- On the Apps and Keys page, copy the User ID1 under My Account Information and save it, this will be used to populate the Journey Manager DocuSign Service Connection properties
- Select your app under Apps and Integration Keys, then select Edit from the ACTIONS dropdown
- On the App page, copy the Integration Key2 under General Info and save it, this will be used to construct the URL in the Grant OAuth Consent to API User below, and also in the Journey Manage DocuSign service Connection properties
- In the Service Integration block, generate an RSA key pair and save the private key to a file, this will be used to upload into the Journey Manager DocuSign service Connection properties
- In the Additional settings block, add 'https://www.docusign.com' and 'https://httpbin.org/get' to the Redirect URIs list
- Click the Save button at the bottom of the page
Follow these steps to grant one-time consent to your DocuSign API user:
- Select the appropriate Development/Production radio button in the form at the bottom of this page
- Paste the saved Integration Key2 into the DocuSign Integration Key field - after you paste the Integration Key value, a new Grant OAuth Consent to API User link will appear at the bottom of the page - click the link to initiate the Consent process in a new tab
- Authenticate as the API user you setup above, and follow the prompts to complete the consent process
- Success is indicated by redirecting to a page at httpbin.org which shows HTTP request details, which you can ignore and close the tab
- When successfully completed, consent has been granted to your API user and you will never need to repeat this step for that user
Follow these steps to configure Journey Manager DocuSign Service Connection properties:
The Journey Manager 22.10 release will contain an updated UI for the DocuSign Service Connection properties page. It will have different field labels and the username and password fields will be removed as they are no longer required. The new page will also include a link to trigger the OAuth consent grant process.
Until you have access to that new page, you can use the form at the bottom of this page to trigger the OAuth consent grant process once you have updated your DocuSign accounts.
Steps:
- Select Services/Service Connections from the main Journey Manager menu, then click DocuSign.
- Make sure DocuSign is selected in the Type dropdown.
- Replace the value in DocuSign Server Hostname/DocuSign Server URL with account-d.docusign.com for development or with account.docusign.com for production - the https:// prefix and trailing / that you have currently configured should be removed.
- Paste the saved User ID1 into the DocuSign API User ID/DocuSign Account ID field - under OAuth the User ID is required instead of the Account ID.
- Paste the saved Integration Key2 into the DocuSign Integration Key field - it is probably the same value you are already using.
- Click the Choose File button then select and upload the RSA private key file3 you saved from the DocuSign App page.
- On the existing Service Connection page, username and password fields are still present and must contain non-empty and valid values to enable the form to submit, but the values are ignored.
- Click the Save button.
For Journey Manager versions earlier than 22.10
For existing Journey Manager installations that do not have the new DocuSign Service Connection properties page, use the input fields and links below to help with granting consent to the DocuSign user you choose to make OAuth-authenticated API calls.
DocuSign OAuth Grant Form
This form is a convenience tool to help you grant OAuth authentication permission to the user you have chosen to make DocuSign API calls from Journey Manager DocuSign services.
Once you enter your DocuSign Integration Key, a link will appear to allow you to login to DocuSign using the API user's credentials, which is all that is necessary to permanently grant OAuth authentication access to that user.
There are different links for Development and Production, chosen by the radio buttons.
After your login succeeds, the user you logged in as has been granted OAuth access and you will never have to repeat the process for that user again. You can ignore the page which shows afterwards. It is just a page which shows some information about the request so you can tell it has succeeded.
If you do not want to use this tool, you will have to construct and launch a URL in one of the following patterns:
| Development | https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature+impersonation&client_id=<Integration Key>&redirect_uri=https://httpbin.org/get |
| Production | https://account.docusign.com/oauth/auth?response_type=code&scope=signature+impersonation&client_id=<Integration Key>&redirect_uri=https://httpbin.org/get |