DocuSign Developer FAQs - Integration Keys and Go Live
DocuSign Developer FAQs ‐ Integration Keys and Go Live
The following are answers to some of the most common questions we receive about Integration Keys and DocuSign's Go Live process. For Developer FAQs on other topics, see the DocuSign Developer FAQs ‐ Table of Contents, or the links under References at the end of this page.
- What is an integration key?
- Who needs an integration key?
- Who does not need an integration key?
- Who should administer the integration key?
- What are the best practices for ISV applications regarding the creation and management of integration keys?
- How do I create an integration key?
- Why does DocuSign have a Go Live process?
- What is required to complete the Go Live process?
- Does the Go Live process cost anything?
- How long does the Go Live process normally take?
- Will my integration key change after Go Live?
- What endpoint should I use to authenticate in the production environment after Go Live?
- What are the most common Go Live errors and what steps can I take to troubleshoot?
- How do I enable and download API logs?
- What constitutes 20+ successful calls for Go Live?
- During Go Live, my production account was not accepted, with the message "The account is not the right type." What type of account is needed?
- What do the “Under Review”, “Review Expired” and “Review Passed” statuses mean during go-live?
Integration keys identify your application to DocuSign for the purpose of communicating with DocuSign APIs. Discover what integration keys are, who does and does not need an integration key, and how to manage them.
What is an integration key?
An integration key is a GUID that identifies an application that integrates with DocuSign REST and SOAP APIs. Integration keys are used by the DocuSign OAuth flows—Authorization Code Grant, Implicit Grant and JSON Web Token (JWT) Grant —to obtain access tokens. Integration keys are not used to identify specific accounts or users.
Who needs an integration key?
Any organization or individual who is developing an application, plug-in, or process that sends API requests to DocuSign needs an integration key. For example, if the application, plug-in, or process you are creating uses the eSignature REST or eSignature SOAP API, you will need an integration key.
Who does not need an integration key?
Who should administer the integration key?
Integration keys should be managed by the organization that owns the application or integration. Most commonly, DocuSign customers integrate DocuSign features into their existing internal or customer-facing applications. As the owner of their existing applications, they would be the owner and administrator of their integration keys.
In other cases, an implementation partner or third-party consultant may create an application or integration on behalf of a DocuSign customer. In these scenarios, the customer is the owner of the application or integration and would be responsible for management of related integration keys.
In cases where a ISV (Independent Software Vendor) partner builds something for resale, the ISV partner owns the application and would be responsible for administration of the key. ISVs should avoid requiring customers to create or manage integration keys to be used with their software.
What are the best practices for ISV applications regarding the creation and management of integration keys?
It is best practice for the creator (or owner) of an integration to create and manage any integration keys required to communicate with the DocuSign system. For our Independent Software Vendors (ISVs), we recommend this practice for two reasons:
- The Go Live process was designed for developers, and end users who are required to Go Live in order to use software that they have purchased through an ISV often have no background in software development. DocuSign Support has received significant feedback from users related to the challenges of taking an integration key live.
- When an ISV requires their customers to use their own integration key, it is often unclear whom to contact when an issue with an integration is surfaced, on the part of both the customer who is using the application and the DocuSign Support team, who may need to refer the user to the application developer.
- ISV Partners, participating in the ISV Referral Program, should email firstname.lastname@example.org or their Partner Representatiive to schedule an App review prior to Go-Live process.
ISV SaaS applications that can secure their integration key and related secrets or RSA keys should use only one integration key for the application. This includes multi-tenant and multi-instance architectures.
Even if an instance of the application is dedicated to a single ISV customer, that instance should use the one integration key obtained by the ISV, so long as the integration key and its settings can be hidden from the ISV customer. For instanced applications, DocuSign prefers that the ISV’s customer not have access to the integration key; it should be managed and controlled by the ISV.
If the ISV creates an instance of the application for a customer, and the customer has complete control over the instance and its settings, then the customer needs to create an integration key.
How do I create an integration key?
Integration keys are created in developer sandbox accounts. Integration keys cannot be directly created on the production systems; please refer to Apps and Keys the DocuSign eSignature Admin Guide for reference.
Once a developer has built his or her application or integration, then the integration key is promoted to production through the Go Live process.
When a key is live in production, it is shown in the Apps and Keys section of eSignature Admin on the production account(s) of the administrator who promoted the key.
Go Live is DocuSign's process for migrating an integration created in the demo environment to the production environment. Go Live is necessary before you can perform real transactions in your integration through the DocuSign APIs.
Why does DocuSign have a Go Live process?
The Go Live process is part of DocuSign’s audited trust processes. It helps ensure the stability of the DocuSign platforms and provides a programming check to the developer. The Go Live process is required for all new API integrations.
What is required to complete the Go Live process?
To go live with the eSignature API you need a developer sandbox account and integration key, 20 or more API calls run using the key in a 24-hour period, and an active production DocuSign account with a supported plan. You also need administrator privileges for the live production account to link the key.
Does the Go Live process cost anything?
No, there is no charge for the Go Live process, and you may promote as many integration keys to the production environment as you would like. All you need is a live DocuSign account on an appropriate plan to which to promote the key, as well as administrator privileges to the account.
How long does the Go Live process normally take?
The automated process can take anywhere from a few hours to three business days. If your integration completes 20+ transactions in 24 hours that comply with DocuSign's resource limits, in addition to having an active live DocuSign account and administrator access to the account, the process can take as little as a few hours.
Will my integration key change after Go Live?
No. After the Go Live process is completed, a new integration key is created in the production environment. The new production integration key will have the same value (GUID) as the developer sandbox integration key, but will otherwise be a completely separate key. The integration key will show a status of live on the developer sandbox account after Go Live completes successfully.
What endpoint should I use to authenticate in the production environment after Go Live?
In the production environment post-Go Live, your application needs to be updated to use production endpoints and related values:
- The URL for the authentication server needs to be updated to https://account.docusign.com
- The base URI for API calls must also be changed: Call the UserInfo endpoint to determine the base URI and account information to interact with the DocuSign API service.
- In addition, if the JSON Web Token (JWT) Grant authorization flow is used, remember to update the impersonated user’s GUID to the value of the API username on a production account.
What are the most common Go Live errors and what steps can I take to troubleshoot?
See the Go Live Troubleshooting Guide to discover how to handle common errors you may encounter during Go Live.
How do I enable and download API logs?
API logging is set on a per-user basis and can be enabled on the Privacy & Security page in your DocuSign account preferences. In the Request Logging section, you can Enable Logging, Disable Logging, Download Logs and Clear Logs.
Enabling logging will capture 50 requests and then disable logging automatically. Logs captured can be downloaded in the form of a ZIP file. If you need to capture more logs, you will need to clear the logs and enable logging again to capture 50 more requests; see API Request Logging for more details.
To see the API logs for your application, login to DocuSign eSignature as the user whose user ID is associated with the application’s access tokens, and then download the logs. If the application impersonates a user, only that user can download the relevant API logs.
What constitutes 20+ successful calls for Go Live?
To pass the go-live process, you'll need to make 20 or more consecutive successful API calls that fall within our guidelines. For additional information, please see our API Rules and Limits documentation.
During Go Live, my production account was not accepted, with the message “The account is not the right type.” What type of account is needed?
The production account used to manage your integration key in production must be a Business Pro account or higher. Ask your DocuSign salesperson if you have questions.
What do the “Under Review”, “Review Expired” and “Review Passed” statuses mean during go-live?
- Under Review – You will see this status after initiating integration key review process by selecting “Start Go-Live Review” dropdown for your ikey. DocuSign system is checking your API calls for the specified time period
- Review Passed – You ikey has passed the initial tests and is ready to be promoted to a production account of your choice. At this point you will need to login to your production account by pressing the “Go Live” button from your review results window.
- Review Expired – ikey passed the review but was never submitted to be linked to a production account. If the ikey is not submitted within a 90-day period, review expires and needs to be done again.