Docusign eSignature Integration 101: Planning your integration

Welcome to the second installment in our series on creating your first Docusign integration. In our first post, we set the groundwork of creating your Docusign developer account and cloning the sample app. Building upon the foundational understanding of Docusign eSignature integration, as explored in blog 1, our focus now shifts from basic setup to the strategic “what” and “why.” This blog aims to provide a conceptual deep dive into Docusign eSignature integration functionality, the essential developer resources available, and the critical considerations for selecting the appropriate authentication flow. 

Unpacking Docusign eSignature integration functionality

The Docusign eSignature REST API forms the bedrock of most integrations, enabling programmatic control over the entire agreement process. Understanding the breadth of these capabilities is crucial for designing comprehensive solutions.

Core eSignature capabilities: The foundation of agreement workflows

The fundamental building block for most Docusign integrations is the envelope, which serves as a digital container for documents, recipients, and the entire signing workflow. The eSignature REST API allows for the programmatic creation and management of these envelopes, making “create an envelope” a common first API call. 

Beyond document handling, the API provides extensive control over recipient management and the signing experience. Integrations can initiate signature requests through traditional remote methods, such as email or SMS invitations. Crucially, Docusign also supports embedded sending and embedded signing, allowing for a seamless user experience where signers are redirected from a website or application directly into the signing session without leaving the host environment. Developers can define various recipient types, including signers, carbon copy (CC) recipients, and certified delivery recipients, ensuring that all necessary parties are involved in the agreement process. 

Docusign streamlines document workflows with template management and document generation. Templates enable standardization with predefined layouts and roles, reducing manual work and errors. Document generation automates personalized agreements by integrating data from existing systems, improving signer experience and workflow efficiency.

The consistent emphasis across these core features is on minimizing manual intervention and maximizing consistency. For developers, this implies that an effective Docusign integration extends beyond merely sending documents for signature. It should strategically leverage capabilities such as dynamic document generation, data prefill, and templating to automate the entire agreement lifecycle. This holistic approach leads to significant operational efficiencies, improved data accuracy, and a more streamlined experience for both senders and signers within an organization.

Advanced features and workflow automation: beyond basic signatures

Beyond the core eSignature functionalities, Docusign provides advanced capabilities that enable sophisticated workflow automation and deeper integration with complex business processes.

A critical component for building reactive, real-time integrations is event notifications, also known as Docusign Connect webhooks. Instead of constantly polling for status updates, an application can subscribe to receive immediate notifications from Docusign whenever an envelope or recipient status changes (for example, signed, completed, voided).This enables a system to react promptly and keep its data synchronized.

Representing a significant advancement in automation, Maestro workflows enable customers to design and deploy streamlined, multi-step agreement processes. The Maestro API facilitates the seamless integration of various Docusign capabilities (such as eSignature) with external services, orchestrating complex business processes that extend beyond simple document signing.

A distinct and powerful integration paradigm is offered by extension apps. Unlike traditional API integrations that embed Docusign functionality into an application, extension apps allow developers to bring custom capabilities directly into the Docusign agreement process via specific “extension points” (for example, within eSignature agreements or Maestro workflows). This enables deep customization, allowing for the addition of external features and even distribution through the Docusign App Center. 

Essential resources for a seamless integration journey

Successful integration relies not just on understanding functionality, but also on leveraging the right tools, documentation, and support ecosystem. Docusign provides a comprehensive suite to empower developers throughout their journey.

Foundational access: developer account and API credentials

The first step for any Docusign integration is to sign up for a free developer account. This account grants full access to build and test integrations within a dedicated developer environment, serving as a crucial sandbox for experimentation without impacting production systems. It is within this environment that developers obtain their API credentials (client ID and secret), which are fundamental for authenticating and making any API calls. Additionally, understanding how to retrieve the correct base URI and account information via the user info endpoint is essential for directing API calls to the correct Docusign environment.

Development accelerators: tools for exploration and prototyping

Docusign offers a comprehensive suite of tools that simplify development, covering API exploration, prototyping, coding, and continuous monitoring and troubleshooting.

Postman collections and the API Explorer are excellent resources for quickly exploring Docusign APIs and testing endpoints without writing extensive code. They provide preconfigured requests and an interactive interface that help developers understand API structures and responses efficiently. Docusign also offers SDKs (software development kits) for multiple languages; our sample app leverages the Node.js SDK. These SDKs wrap the raw REST APIs with intuitive objects, properties, and methods, simplifying API interactions and reducing boilerplate code, allowing us to work efficiently in our preferred language environment. 

Demystifying authentication flows: Choosing the right path

Authentication is the cornerstone of any secure API integration. Docusign leverages OAuth 2.0, offering several grant types, each suited for different application architectures and user interaction models. Understanding these conceptually is vital for selecting the most appropriate and secure method for a specific integration.

Understanding OAuth 2.0 grant types for Docusign

Docusign supports four primary OAuth 2.0 flows to obtain access tokens, which are essential for making authenticated API calls. The choice among them depends heavily on an application’s architecture and how users interact with it.

• Confidential Authorization Code Grant (ACG):

  • Conceptual use case: This is the most common and secure choice for web applications with a secure back-end server capable of storing a client secret. It is used when individual users, possessing their own Docusign accounts, log in to the integrated application, and the integration needs to perform actions on their behalf.

  • Mechanism: The flow involves the user granting consent via a browser redirect. The application’s secure server then receives an authorization code, which is exchanged for an access token (and typically a refresh token) using the client secret. Subsequent API calls are made using this access token.

  • Advantages: This grant is considered very secure because the client secret is stored on a controlled, secure web server. It is suitable for most general web application use cases and offers a simpler implementation model than JWT for individual user authentication. It provides long-lived refresh tokens, enabling continuous access without frequent re-authentication, and can optionally include Proof Key for Code Exchange (PKCE) for an additional layer of security.

• Public Authorization Code Grant (ACG with PKCE):

  • Conceptual use case: This flow is specifically recommended for public clients such as single-page applications (SPAs) or native mobile apps that cannot securely store a client secret. Like Confidential ACG, it is used when individual users authenticate with their own Docusign accounts and the application acts on their behalf.

  • Mechanism: It functions similarly to the Confidential flow, but incorporates Proof Key for Code Exchange (PKCE) for added security. PKCE ensures that the application initiating the authentication flow is the same one that completes it, mitigating risks without requiring a client secret.

  • Advantages: It offers the same high level of security as Confidential ACG (when PKCE is used) without the need for a secure server to store a secret. It is simpler to implement than JWT for user-present scenarios and provides refresh tokens for extended access. However, it requires the user to be actively present to authenticate, making it unsuitable for autonomous background processes. earn how to get an access token using ACG with PKCE in our walkthrough video:

• JSON Web Token (JWT) Grant:

  • Conceptual use case: This flow is primarily designed for system-to-system integrations where a user is not present or when a single system account is used for all application users. It allows an integration to impersonate a specific user on a long-term basis without that user being actively logged in. This is ideal for automated workflows, batch processing, or services that require unattended access to Docusign APIs.

  • Mechanism: The application generates a JSON Web Token (JWT) that contains assertions about its identity and the user it wishes to impersonate. This JWT is then exchanged for an access token. This flow requires prior administrative consent for the application to impersonate the designated user. Learn how to get an access token using JWT Grant in our walkthrough video:

  • Advantages: Enables truly automated workflows without requiring user interaction after initial setup. It avoids the complexities of managing individual user refresh tokens. When used with Docusign Admin, it can facilitate obtaining consent for all users within an organization’s domain simultaneously, simplifying large-scale deployments.

• Implicit Grant:

  • Conceptual use case: While supported historically for single-page and mobile applications, this flow is explicitly not recommended for new integrations due to its inherent security limitations, such as access tokens being exposed in URL fragments.

  • Recommendation: Developers are advised to use Public Authorization Code Grant with PKCE as a significantly more secure alternative for client-side applications.

Why JWT for our sample app? 

In the context of our sample application, which focuses on automating tenant agreement actions, we have chosen the JWT Grant flow because it aligns perfectly with a common integration pattern: using a single Docusign login for all application users. Our application is designed to act as a service integration that directly interacts with a Docusign account to generate and send tenant agreements, rather than requiring every end-user to authenticate individually. This means the application obtains permission to impersonate a specific user on a long-term basis without that user needing to be actively present and logged in. This approach simplifies authentication management within the application, making it ideal for automated processes and backend services where continuous, unattended access to Docusign APIs is required for tasks like agreement generation and sending.

jwtController.js: The heart of JWT authentication in our sample app 

As a continuation of our discussion from our first post about setting up your developer account and cloning the sample app, you will notice a file jwtController.js in your cloned app. The jwtController.js in your app plays a pivotal role in handling the JWT (JSON Web Token) Grant authentication flow for integrating with the Docusign APIs. This is where the practical implementation of the JWT Grant comes to life.

It implements several key functionalities:

• Creating and sending a JWT token to obtain an access token.

• Checking if the current access token is valid and refreshing it if necessary.

• Retrieving user information using the access token.

• Handling user login and logout.

• Checking to see if a user is logged in.

Choosing the right authentication flow

When selecting an authentication flow, the primary factor is whether users will directly authenticate with their Docusign credentials (requiring their presence) or if the application will authenticate as a system user for background operations without direct user interaction. For direct user authentication, Authorization Code Grants are suitable. For system-level operations, JWT Grant is the appropriate choice. This core distinction simplifies the initial architectural decision.

Another key factor is the application’s ability to store a client secret securely. If the application has a secure backend server capable of protecting a client secret, the Confidential Authorization Code Grant is the most secure and recommended choice for traditional web applications. If the application is purely client-side (for instance, a single-page application or a mobile app) and therefore cannot securely store a secret, the Public Authorization Code Grant with PKCE is the secure and recommended alternative.

The following table provides a concise comparison of the Docusign OAuth grant types and acts as a summary of what was described above. This consolidated view of critical attributes (user presence, secret storage, security level) allows for efficient comparison, directly addressing the need for conceptual guidance in choosing the right authentication path.

Conclusion: Charting your course for a robust Docusign integration

Building on the groundwork laid in Blog 1: Docusign eSignature Integration 101: Setting the Foundation, this post has delved into the conceptual aspects of Docusign capabilities and the strategic choices involved in integration. The choice of authentication flow is a foundational architectural decision that impacts security, operational simplicity, and user experience. As highlighted with our sample app, JWT is particularly well-suited for integrations that operate with a single system account, enabling automated, unattended access to the Docusign APIs. 

In our next blog post, we will provide step-by-step instructions to build and run the sample application, putting these concepts into practice, and preparing your integration for a successful agreement process.

Additional resources

• Docusign eSignature Integration 101: Setting the foundation

• Docusign Developer Center

• Docusign API Documentation for Node.js