From the Trenches: Authentication with the Apex Toolkit

Quite a few programmers contact Docusign Developer Support asking us about how to programmatically control authentication using the Apex Toolkit, our eSignature API interface included in the Docusign Apps Launcher. It turns out that this is not necessary, and all you need is to ask the user for consent.

If you haven’t yet started using the Apex Toolkit, check out my colleague Ben Dowling’s Hello World example. For those of you further down the line, you may find that as you add new Docusign users, they are not always able to execute the Apex Toolkit classes that you have developed. A common error is, “You have not granted or revoked your consent to be impersonated by Docusign App Launcher.”

Docusign Apps Launcher is tightly integrated with Salesforce and, behind the scenes, when the Apex Toolkit calls out to the Docusign API, Apps Launcher checks for an access token. If none is found, the Apex Toolkit will attempt to exchange a JSON Web Token (JWT) for an access token. The application is not allowed to authenticate to Docusign on behalf of the logged-in Salesforce user until the user grants the application a one-time permission to impersonate. Users grant consent in the Docusign Apps Launcher UI when they click the Authorize button as described in Step 3 of How to authenticate in our Apex Toolkit documentation. 

Programmers, naturally, want to take control of authentication and do the JWT authentication themselves, but this is unnecessary and actually not possible using the Apex Toolkit. All you have to do is catch the CONSENT_REQUIRED error, then prompt the user to grant consent, check for success, and then try your Apex Toolkit code again. We detail the steps in this how-to guide.

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter