Integration Keys Explained: A Practical Guide for ISVs

Integration keys are GUIDs: unique 32-digit (128-bit) hexadecimal numbers that serve as globally unique identifiers (GUID). In Docusign, integration keys are essential credentials used by applications to authenticate and integrate with Docusign APIs. They uniquely identify the application during API interactions, ensuring secure communication between the application and Docusign’s platform. When setting up API integrations, developers need to register their applications within their Docusign developer accounts to obtain these keys, ensuring that their apps can securely manage digital transactions and document workflows. Integration keys are also referred to as client IDs and API keys, and historically have also been referred to as integrator keys. 

This blog post delves into the intricacies of integration key management, providing insights on when and how to use them effectively for independent software vendors, and how to encrypt and store them in your codebase.

Where integration keys are stored in Docusign

Integration keys in Docusign are stored within the developer's Docusign account. You can create and manage yours by logging into your Docusign account as administrator and navigating to the Apps and Keys section, where you can view, create, and manage integration keys; see the official Docusign Support page for details. 

Who needs integration keys and who does not

Anyone working in app development, system administration, or API management who sends API requests to Docusign will need to interact with integration keys.

Not all DocuSign services require an integration key, however. For instance:

• PowerForms initiated via their URL

• Clickwraps that utilize DocuSign’s JavaScript code embedded in web pages

• DocuSign Connect listeners that do not call a DocuSign API

These services can operate without an integration key because they do not interact with DocuSign APIs directly. Instead, they leverage DocuSign’s built-in functionalities, allowing customers to use the system without the need for an integration key.

Integration key management

For independent software vendors, we suggest the following best practices and guidelines; see Integration key management for ISVs on the Developer Center for more details.

The need for integration keys varies depending on your application’s architecture:

1. SaaS multi-tenant applications:

   • Integration keys required: Only one integration key is needed, regardless of the number of customers.

   • Security considerations: Customers must not have access to the secret information related to your integration key. This includes secret keys, RSA key pairs, and redirect URIs.

2. SaaS multi-instance applications with shared identity/authorization:

   • Integration keys required: A single integration key suffices for all customers.

   • Security considerations: Make sure that the integration key’s secrets remain inaccessible to customers.

3. SaaS pure multi-instance applications:

   • Integration keys required:

     • If using either the Authorization Code Grant or the Implicit Grant flow: You usually need one integration key per instance if these flows are used, because each instance will typically have a different redirect URI. 

     • If using the JWT Grant flow: It may be possible to use a single integration key for all instances, since the redirect URI is only used during the consent process.

   • Security considerations: Customers should not have access to the integration key’s secrets.

4. On-premises applications:

   • Integration keys required: Each customer requires their own integration key because the secrets cannot be securely protected.

   • Security considerations: You will need to provide different redirect URIs for each customer, and protect against the potential exposure of the integration key and its secrets during installation.

Integration keys limits

Each Docusign account is limited to 100 integration keys. If your integration requires a unique key for each customer, you’ll need to collaborate with the Docusign Partner Solutions team as you approach this limit. 

Managing multiple integration keys

If your application architecture necessitates a unique integration key for each deployment (common in on-premises or customer-controlled environments), consider the following:

• Management responsibility: Your company should create and manage these integration keys to streamline the process and enhance customer satisfaction.

• Customer experience: Requiring customers to obtain their own integration keys and pass the Go-Live/AppReview process can be time-consuming and may lead to frustration.

Best practices for integration key naming

Choose an integration key name that clearly reflects your company and product. This is crucial, because customers are prompted to consent to access during the integration process. An ambiguous or unfamiliar name might raise security concerns in users’ minds and hinder the consent process.

How to encrypt an integration key:

This section provides a simple Python code example to encrypt an existing integration key using AES-based symmetric encryption (Fernet). Here I am using Python’s cryptography library for encrypting the integration key. As integration keys are essentially GUIDs that identify your integration, I will use the term GUID for integration keys interchangeably in my code for a cleaner naming convention experience.

After installing the cryptography package, you can easily encrypt the GUID, making it secure for storage or transmission, and decrypt it when needed.

Steps:

1. Install cryptography: pip install cryptography

2. Encrypt the integration key (GUID): Here’s the Python code for encrypting and decrypting a GUID:

   Copy to clipboard

   from cryptography.fernet import Fernet
   # Your existing GUID
   guid = "your integration key"
   print(f"Original GUID: {guid}")
   
   # Generate a key for encryption
   key = Fernet.generate_key()
   cipher = Fernet(key)
   
   # Convert GUID to bytes and encrypt it
   guid_bytes = guid.encode()
   encrypted_guid = cipher.encrypt(guid_bytes)
   
   print(f"Encrypted GUID: {encrypted_guid}")
   
   # Decrypt the GUID to verify
   decrypted_guid = cipher.decrypt(encrypted_guid).decode()
   print(f"Decrypted GUID: {decrypted_guid}")
   

   Show more

How it works:

• GUID: You pass an existing integration key.

• Key generation: The script generates a symmetric key (AES-based) to encrypt the GUID.

• Encryption: The GUID is converted to bytes and encrypted using the key.

• Decryption: The encrypted GUID can be decrypted to verify its accuracy.

You can save the generated encrypted GUID in various secure locations, depending on your application requirements:

1. Database: Store the encrypted GUID as a string in a database like MySQL, PostgreSQL, or MongoDB.

2. Secure file storage: Save it to a file, such as a text or binary file, and secure it using file system permissions.

3. Cloud storage: Use cloud providers like AWS S3 or Azure Blob Storage, ensuring access is tightly controlled.

Encryption ensures that integration keys (GUIDs) are securely stored or transmitted, protecting them from unauthorized access. Whether you’re managing sensitive data or handling transactions, securing identifiers is essential. With this approach, you can incorporate strong encryption practices into your applications with minimal effort.

Conclusion

Effective integration key management is vital for ISVs and customers to maintain secure and efficient operations. By understanding your application’s architecture and following best practices, you can optimize the integration process, enhance security, and provide a better experience for your customers.

Key takeaways:

• Assess your application’s architecture to determine the integration key requirements.

• Use a single integration key when possible to simplify installation and management.

• Protect the integration key’s secrets to maintain security.

• Collaborate with Docusign for support and to manage limitations.

Additional resources

• Docusign Developer Center

• Docusign Developers Community

• @DocusignDevs on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter