Skip to navigation
How-to guides

How to authenticate

View as Markdown

In the latest releases (v2+) of the Apex Toolkit, we have refactored admin and end-user logins to leverage Docusign OAuth and Docusign Admin. We made this change to improve the security and administrative controls over the login process. While this change is very beneficial overall to our developers and administrators, it entails additional overhead for integrations.

After installing or upgrading Apex Toolkit v2+, you must authenticate with Docusign. This step is required for new installs or upgrades from v1.x.

Step 1. Connect Salesforce to your Docusign account

  • Open the Salesforce application menu using the icon in the upper left corner. From that menu, open the Docusign Apps Launcher.
Salesforce application menu
  • To log in to your Docusign developer account, expand Advanced Options and select Log in to Demo Account. You may have to enable pop-up windows in your browser. In the login dialog box that appears, enter your Docusign credentials and select Accept when prompted for consent. You may have to authenticate with Salesforce again after this step.
  • If more than one account is associated with your Docusign credentials, you’ll be presented with a list. Choose the Docusign account you prefer and click Select. You may have to authorize Docusign to communicate with Salesforce. Start this process by selecting Allow Access and follow the prompts.
Log in to Docusign

Step 2. Add Salesforce users to your Docusign account

Once the setup admin authentication is complete, you can add additional users to your Docusign account.

Open Docusign Apps Launcher from the Salesforce app menu. Navigate to the Docusign Setup tab and select User Management, then Add Users. Search for the users you want to add and select the checkbox next to their names. Select Add Users once complete.

The newly added users begin in the Pending state. They will switch to Active once they have granted consent.

Adding Salesforce users to your Docusign account

Users of your application must grant their consent for the API to act on their behalf. There are two methods to accomplish this. If you are using Docusign Admin, you can grant consent on behalf of your users following the steps outlined in How to obtain admin consent for external applications. If you have claimed a domain, you can authorize the Docusign connected app for the following scopes:

signature impersonation
account_product_read
account_product_activate
spring_write
spring_read
manage_app_keys
spring_content
group_management_read
group_management_write
clm_ui

If this is not an option for your integration, you must obtain individual consent from each user. Obtaining individual consent requires your application to redirect users to the Docusign authentication service. Upon granting consent, the user is returned to the Salesforce record.

From a Salesforce record page, select the gear icon in the upper right and then select Edit Page. Next, drag the Docusign Envelope Status component from the Custom list on the left to the desired location. You must have My Domain enabled and deployed for this component to be visible. Click Save when finished. Follow any prompts to activate the page for your users. The component should now be visible to your users on the record page.

Add Docusign Envelope Status component

While straightforward, the Docusign Envelope Status component option is not ideal for integrations where you need more control over the process or where the component cannot be used (e.g., Communities). As of Apex Toolkit v2.2 you can initiate the consent flow from your code and afterwards redirect the user to a page of your choosing. See dfsle.AuthService.getLoginUrl and How to obtain consent for details.