From the Trenches: Manage your DocuSign integration keys
To communicate with DocuSign APIs, integrations must authenticate, and a required piece of the authentication process is the integration key. DocuSign generates and assigns integration keys to identify integrations (apps) that you register in your developer (demo) account. While integration keys are generated only once, in your developer account, they are replicated into a production account of your choosing when you promote your app to production via the Go-Live process.
Are you an admin?
Although DocuSign assigns integration keys to the apps you create in your developer account, those integration keys are not linked to your individual user, but to the account itself. This account, whether a developer account or (once you’ve promoted the app) a production account, is referred to as a management account. For this account, only users with administrative permissions (who have a DSAdmin permissions profile) may manage the integration keys assigned to it. Many developers have developer accounts with just themselves as the only user (who is by default the admin) and may not be aware of this distinction.
To verify that you have admin permissions, log in to your account and see if you have a Settings menu at the top; if you do, you’re an admin on the account. The Settings menu gives you access to the Apps & Keys page, where you can manage integration keys for your apps. Nevertheless, being an admin in one DocuSign account does not guarantee access to manage a given integration key’s configuration if that key is linked to a different management account.
Legacy authentication and integration key management
One reason why some integration keys may have different management accounts is the evolution in DocuSign API authentication. Prior to 2021, most DocuSign customers were using legacy authentication. With legacy authentication, the only information the integration needed to authenticate its API calls was the integration key, the user's email address (username), and the user's password. However, starting in September 2021, DocuSign began retiring legacy authentication, starting the process of migrating customers to the more secure OAuth 2.0.
With OAuth 2.0, developers have to configure their integration key with a secret key or private key, depending on their choice of authentication flow, and to do this, they must have access to the integration key’s management account.
Here is the real problem: Over time, as part of updating their authentication methods, some customers migrated from one account to another, and the original management account for their integration key(s) was closed. In some other cases, the original management account had only one user admin, who left the company. In either case, unfortunately, many customers now find themselves without admin access, or with no access at all, to the management account of their integration key(s). If the customers have had no reason to change the integration key’s settings, they may have been using it for a long time without even realizing they lost access to its management account!
Resolving the problem
The good news is that there are fixes for this problem:
The first option is that the integration key can be moved between production management accounts. However, there is a catch: The customer needs to provide a user admin written confirmation from both the original (current) management account and the destination management account.
Well, what if the only admin user left? DocuSign allows for organization admins to act as the original management account’s admin. Note: the organization must have a claimed domain, and the user who initially requested the Go-Live review must be part of the same domain.
The other option: In cases where the only admin user is not present and there is no organization, all you can do is to generate a new integration key in your developer account, pass that integration key through the Go-Live process, and then promote it to a new production account.
Account management practices
How best to prevent such issues depends upon the size of your organization and how your org manages its DocuSign accounts. It’s worth considering the following suggestions for each DocuSign account used for app development or production:
- Use a single developer account shared by your development team, creating a user for each dev.
- Use a single production account as well. This account should only need admins, who will manage the Go-Live process for each app your org promotes.
- Create at least two admin users on each account. That way, if one user leaves the org, you’ve still got an admin.
- Establish an admin user on each account not linked to an individual, and securely manage its credentials.
- Ensure all integration key credentials, such as the secret and private keys, are kept in a secure place. In this way, the credentials can still be utilized even if you lose access to the management account.
