Skip to navigation
Platform 101Build a Docusign integration

Configure your app

View as Markdown

This topic describes the settings associated with your Docusign account and what you can configure for each of your apps or integrations. Each section contains:

  • An overview of one setting of your account or API integration
  • What that setting is used for
  • An expandable workflow detailing how to configure that setting

Integration key

Each of your integrations that uses the Docusign platform is identified by one or more integration keys. An integration key is a GUID value that identifies your integration (or, in specific cases, a website, system, or scenario within your integration) and links it to configuration values.

  • An integration is a product that incorporates Docusign API functionality.
  • An app is a set of parameters that are used to identify and configure an integration’s access to the Docusign platform. Each app has exactly one integration key. While not recommended, an app can be used in multiple integrations.
  • When you Go-Live to move your app to the production environment, its integration key is duplicated in the production environment rather than moved. This means you can continue to use that integration key in the developer environment as well as in production.

Best practice: Docusign recommends using exactly one integration key (and one app) per integration. Using an app (and its associated integration key) within multiple integrations can cause difficulty troubleshooting problems and can complicate the Go-Live process. Using a unique integration key for your app allows both you and Docusign, should you need support, to monitor and track the API activity for your specific integration. Also, if you’re already using APIs for your other integrations, any throttling or preventative measures that Docusign takes on the platform side for a specific integration do not affect your other Docusign-enabled processes.

You can register your integration and add an integration key with Docusign. See How to get an integration key.

Best practice: Make sure that the App Name associated with your integration key will help your users identify that the app is part of your service or product. If your users do not recognize the name, you risk having some users revoke consent, forcing them to grant consent again to continue using your integration.

All other configurable settings tied to an integration are referenced by the Docusign authorization service through its integration key (or, in rare circumstances, keys), which must be included in your integration’s initial authorization call.

Walkthrough video

You can also see a walkthrough video of what an integration key is and how it works in the Docusign platform, shown below.

You can obtain an integration key using the Docusign Admin administrative tool, as described in the following steps.

Note: Apps and their associated integration keys cannot be deleted. Use caution when creating an app to obtain an integration key.

  1. Create or login to your developer account Create a new developer account, if you do not already have one, following the prompts and entering all required information. At the end of the process, you will be logged into your developer account. If you have previously created a developer account, log in before continuing.

  2. Access the Apps and Keys page Open the Apps and Keys page for your developer account.

  3. Add and configure a new app To add and configure a new app, follow these steps:

    1. You’ll see a dialog box to enter your app name. Give your app a short, but descriptive name, such as Docusign HR Integration. Entering the name of your new app in the Add API Integration Key dialog box

    2. Select ADD to add your app. Your app is automatically assigned an integration key (GUID) value that cannot be changed, as shown here:

      Your app is automatically assigned an integration key

Next steps: Choose your integration’s authentication method.

Secret key

A GUID value that is only shared with your web server and the Docusign platform. To ensure security, this value must be stored securely in your web server. Even if a malicious attacker were to intercept your authorization code, they would not be able to exchange it for an access token without also knowing your secret key.

It is essential to protect your secret key. Secret keys must never be sent to a browser or otherwise disclosed to a potential attacker.

Note: You are only able to view your secret key immediately after creating it, so be sure to save it or record it to a safe place. To ensure its security, there is no way to go back and view it again after you close the window.

You can have more than one secret key per app.

Security recommendation: Rotate your secret keys periodically, store them in a secure system or library if available, and do not include them in software repositories.

Note: Changes or additions to your secret keys can take up to five minutes to fully propagate across the Docusign platform.

Secret keys are used only in the Authorization Code Grant flow. If you plan to use one of the other authentication flows, you do not need to add a secret key.

To add a secret key for your app, use the following procedure.

You must have already added an app to add a secret key to it.

  1. Access the Apps and Keys page Open the Apps and Keys page for your developer account.

  2. Select the app to configure On the list of your apps and integration keys, find the row of the app to configure, then select EDIT from its ACTIONS context menu. This will open the configuration page for that app.

  3. Set User Application to Yes, indicating that your application can securely store a secret key.

  4. Add a secret key Select ADD SECRET KEY, which creates a new, automatically generated GUID value that represents a secret key, as shown here:

    Image of secret key management UI

    Copy the secret key to a safe location (such as an environment variable, text file, or database) by selecting the copy icon shown in the image**.

    Important:** You need to copy the secret key to a safe location before you save your integration key settings. After your integration settings are saved, secret keys are masked for security reasons and cannot be revealed again. If you don’t copy it first, your only option will be to delete the secret key and add a new one.

    Select SAVE to save the secret key.

Redirect URI

The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication when using the Authorization Code Grant or Implicit Grant authentication flow. If your integration is using the JSON Web Token (JWT) Grant flow, a redirect URI is also used for the individual consent process.

You must define at least one redirect URI to implement any authentication scenario. You may set more than one redirect URI per app.

Note: Changes or additions to your redirect URIs can take up to five minutes to fully propagate across the Docusign platform.

To set a redirect URI for your app, use the following procedure.

You must have already added an app to add a redirect URI to it.

  1. Access the Apps and Keys page Open the Apps and Keys page for your developer account.
  2. Select the app to configure On the list of your apps and integration keys, find the row of the app to configure, then select EDIT from its ACTIONS context menu. This will open the configuration page for that app.
  3. Set your redirect URI Select ADD URI, which displays a new text box for you to enter the URI (URL) where your authenticated users will be redirected. Select SAVE. You’ll see your newly configured integration key settings in the list of apps and integration keys on the Apps and Keys page.

RSA key pair

An RSA key pair is used to encrypt your token in the JWT Grant authentication flow to provide assurances of authorship and data integrity.

Note: You are only able to view your RSA key pair immediately after creating it, so be sure to save it or record it to a safe place. To ensure its security, there is no way to go back and view it again after you close the window.

An RSA key pair is required to use the JWT Grant authentication flow. If you plan to use one of the other authentication flows, you do not need to add an RSA key pair. See How to get an access token with JWT Grant for details.

Security recommendation: Rotate your RSA key pairs periodically, store them in a secure system or library if available, and do not include them in software repositories.

Note: Changes or additions to your RSA key pairs can take up to five minutes to fully propagate across the Docusign platform.

To add an RSA key pair for your app, use the following procedure.

You must have already added an app to add an RSA key pair to it.

  1. Access the Apps and Keys page Open the Apps and Keys page for your developer account.

  2. Select the app to configure On the list of your apps and integration keys, find the row of the app to configure, then select EDIT from its ACTIONS context menu. This will open the configuration page for that app.

  3. Add the RSA key pair Select GENERATE RSA, which creates a new, automatically generated GUID value that represents the ID for the private and public key pair, as shown here:

    Select GENERATE RSA to have Docusign auto-generate an RSA key pair for you

    Copy the private key to a safe location (such as an environment variable, text file, or database) by selecting the copy icon shown in the image. You do not need to copy the public key.

    Important: You need to copy the private key to a safe location before you select CLOSE. After you close this screen, RSA key pairs are masked for security reasons and cannot be revealed again. If you don’t copy it first, your only option will be to delete the RSA key pair and add a new one.

    Select CLOSE, then select SAVE.

User ID

A GUID value that uniquely identifies a Docusign user.

For authentication, every user access token is associated with a specific user ID. You can always find your User ID on the Apps and Keys page.

  • In the Authorization Code Grant and Implicit Grant authentication flows, the user who completes the authentication process (by entering their email and password) will be the associated user.
  • In the JWT Grant authentication flow, a user ID identifies the user to be impersonated with the resulting access token.

This value is automatically set when you create your account and cannot be changed later.

API Account ID

A GUID that identifies your account. Most Docusign API calls include this value (also called account ID) as the accountId parameter in the call’s path. You can find your API Account ID on the Apps and Keys page.

This value is automatically set when you create your account and cannot be changed later.

Authentication method

This is an important choice that determines how your integration will be authenticated and obtain your users’ consent to act on their behalf. By default, Docusign uses the most secure OAuth grant type, which is Authorization Code Grant.

For more information about determining which OAuth grant type is right for your integration, see Authenticate.

To choose an authentication type for your app, use the following procedure.

You must have already added an app to choose an authentication method for it.

  1. Access the Apps and Keys page Open the Apps and Keys page for your developer account.

  2. Select the app to configure On the list of your apps and integration keys, find the row of the app to configure, then select EDIT from its ACTIONS context menu. This will open the configuration page for that app.

  3. Choose authentication type In the Authentication section, select options based on the authentication method your app will use.

    1. Public Authorization Code Grant: In the User Application section, when prompted whether your application is able to securely store a client secret, select No. In the Authentication Method for your App section, select Authorization Code Grant with Proof Key for Code Exchange (PKCE).
    2. Confidential Authorization Code Grant: In the User Application section, when prompted whether your application is able to securely store a client secret, select Yes. To use the Confidential Authorization Code Grant flow, you must add a secret key. You can also enable the Optional PKCE code challenge for Confidential Authorization Code Grant by selecting the Require Proof Key for Code Exchange (PKCE) checkbox.
    3. Implicit Grant: In the User Application section, when prompted whether your application is able to securely store a client secret, select No. In the Authentication Method for your App section, select Implicit Grant.
    4. JSON Web Token (JWT) Grant: In the User Application section, when prompted whether your application is able to securely store a client secret, select Yes. To use the JWT Grant flow, you must add the RSA key pair in the Service Integration section.

Next steps: Set one or more redirect URIs.

CORS configuration

CORS (Cross-Origin Resource Sharing) configuration enables you to define settings that determine whether Docusign will accept API requests sent by your app directly from a script running in a web browser. Browsers send these requests using the CORS protocol. Populate the CORS configuration settings if your app is a single-page application (SPA) or other browser-based application that does not route API requests through a server. See Single-page applications and CORS for more information. If your app routes requests through a server, you do not need to configure these settings.

If your app will make CORS requests, you must select one of the supported authentication methods: Authorization Code Grant with the Require Proof Key for Code Exchange (PKCE) option enabled or Implicit Grant. See Include required scopes during authentication for information.

If you add CORS configuration settings for your app, both CORS and non-CORS requests can be made under the app’s integration key. For example, an SPA can send CORS requests and a client-server integration can send non-CORS requests using the same integration key.

When Docusign receives a CORS request, in addition to validating it against the app’s CORS configuration settings, Docusign checks whether CORS is enabled for the account. An account administrator controls whether CORS is enabled for their account membership. See Enable or disable CORS for apps for more information.

Note: Changes or additions to the CORS configuration can take up to five minutes to fully propagate across the Docusign platform.

To set CORS parameters for your app, use the following procedure.

You must have already added an app to set up a CORS configuration for it.

  1. Access the Apps and Keys page Open the Apps and Keys page for your developer account.

  2. Select the app to configure On the list of your apps and integration keys, select the name of the app to configure. This will open the configuration page for that app.

  3. Add origin URLs Select Add Origin URL, which displays a new text box. Enter the URL from which your SPA or browser-based application will launch API requests. If you need to define additional origins, select Add Origin URL again and enter the next URL. You can enter up to 20 origins per app. Docusign returns an error in response to any CORS request whose origin has not been defined in this section.

    When defining origins, follow these guidelines:

    • Include all origins that will send API requests from a browser.
    • Identify origins at the domain or subdomain level. Don’t specify directories or file names in the URL. For example, if your script resides at https://example/com/scripts, define the origin as https://example.com. See Definition of an origin for details about what differentiates one origin from another.
    • Make sure the URL has the correct protocol (http or https) in the origin. Requests will be rejected if they come from an https origin and you have configured the origin URL with http, and vice versa.
    • On the developer environment, you can use localhost as an origin, with both http and https URLs. Non-localhost origins on the developer environment must use https. On production, neither localhost origins nor http origins are allowed.
    • If an origin has a nonstandard port, include it in the URL. An origin URL with no explicit port is assumed to use the default, and if the request does not originate from that port, it will be rejected.

  4. Allow CORS for OAuth calls If the integration’s authentication method is Authorization Code Grant with PKCE, check the Allow CORS for OAuth calls box. This option does not appear if the authentication method is Implicit Grant or if the app type is Native OS Application.

  5. Select the allowed HTTP methods In the Allowed HTTP Methods section, select the methods that Docusign should permit in API requests from your SPA or browser-based application. Docusign returns an error in response to any CORS request whose method has not been selected in this section.

    Note: For the best security, only enable the HTTP methods that your app uses.

    Selecting allowed HTTP methods for your CORS configuration

  6. Select Save.

A link to a custom privacy policy document to which your users agree when they grant consent for your integration to act on their behalf.

A link to a custom document delineating terms of use to which your users agree when they grant consent for your integration to act on their behalf.

Next steps