Using DocuSign to Request Signatures within your App

Many business software applications require users to sign legal agreements, such as a real estate contract when buying a house. Getting a user to electronically sign a document seems like it should be simple, but doing so in a secure and user-friendly way is hard enough that it's usually best to delegate this job to 3rd party software.

DocuSign  is the leading platform for this. While this article focuses on the most basic use case for DocuSign (getting the user to sign a document), this just scratches the surface of what DocuSign can do. DocuSign publishes a number of APIs  — the one we'll be using is the eSignature API .

What We're Building

The eSignature API is quite extensive and supports many different use cases, such as embedding the document signing process in your application, or sending out an email that contains a link to a document that's hosted by DocuSign. We will be implementing the embedded signing use case in a Node.js web application.

Calling the eSignature API requires a client secret, which we'll store securely in the Zero secrets manager. We will use the Zero TypeScript SDK  to retrieve the client secret when the Node.js application starts up.

🔗 The full code for this example is available in the zerosecrets/examples  GitHub repository.

Secure your secrets conveniently

Zero is a modern secrets manager built with usability at its core. Reliable and secure, it saves time and effort.

Sign Up Now

Downloading the Starter Project

Integrating with the eSignature REST API is very involved compared to most of the other integrations we've featured on the Zero blog. Fortunately, DocuSign provides a Quickstart wizard  that gives you a fully-functional sample project based on your answers to a few questions. Here are the steps to completing the wizard:

1. Follow the link to create a new DocuSign developer account, or log in to your existing account. (I had to disable my ad-blocker for the sign up page to work correctly.)
2. Enter the application name of your choosing.
3. Select Node.js for the language.
4. Select "Authorization Code grant embedded signing example" for the project type.

After downloading the starter project, you can run it by navigating to the quick_acq directory and running npm install followed by npm start. This will launch a simple application:

The form will be prefilled with your DocuSign account information. Clicking the "Submit" will display a sample document and request your signature. When you have signed the document, you'll be redirected back to the main page of the sample app.

Storing the Secret in Zero

Now, log in to Zero and create a new project. Copy the Zero token to a safe location on your local computer — we'll provide this token to the Node.js app via an environment variable.

In the DocuSign starter code, open config/appsettings.json. Copy the value of the dsClientSecret key and delete this line from the file. We don't want the secret to be committed to our git repository. You should also delete the private.key file, which is not actually used by the sample code.

Create a new secret in Zero and paste in the client secret:

Integrating with Zero

The next step is to modify the code to fetch the client secret from Zero when the application starts up. First, we need to install the Zero TypeScript SDK . In the quick_acg directory, run

npm install @zerosecrets/zero

Then, edit config/index.js, adding a function that uses the SDK to retrive the secret from Zero:

exports fetchDsClientSecret = async () => {
  if (!process.env.ZERO_TOKEN) {
    throw new Error('Did you forget to set the ZERO_TOKEN environment variable?')
  }

  const result = await zero({
    token: process.env.ZERO_TOKEN,
    pick: ['docusign'],
  }).fetch()

  return result.docusign.client_secret
}

Next, we need to update the main entrypoint quickACG.js to call fetchDsClientSecret. Since the code is using old school CommonJS modules, we can't use a top-level await statement. So to make it work, we'll need to wrap the server startup code in an async function. The function declaration should be placed just above the line

if (dsConfig.dsClientId && dsConfig.dsClientId !== '{CLIENT_ID}' &&

and include all of the code below that. Then at the bottom of the file, we'll use a .then() to feed the output of fetchDsClientSecret into startApp. The final result should look like this:

async function startApp(dsClientSecret) {
  // Add this line:
  dsConfig.dsClientSecret = dsClientSecret

  if (
    dsConfig.dsClientId &&
    dsConfig.dsClientId !== '{CLIENT_ID}' &&
    dsConfig.dsClientSecret &&
    dsConfig.dsClientSecret !== '{CLIENT_SECRET}'
  ) {

  /* Server startup code here */
}

fetchDsClientSecret().then(startApp)

Running the App with Zero

The steps for running the application are the same as before, but now you'll need to provide the Zero token as an environment variable:

ZERO_TOKEN='<YOUR_ZERO_TOKEN>' npm start

The document signing flow should work exactly the same as before, with the DocuSign client secret being fetched from Zero during startup.

Closing Thoughts

Embedded signing is just one of the many workflows supported by DocuSign. That said, this general approach of beginning with the DocuSign-provided sample code and updating it to work with the Zero SDK should work for the other eSignature workflows too. Good luck with your project!