DocuSign is an e-signature integration that allows you to manage digital signatures on your contracts and other documents. This page focuses on the initial setup for a DocuSign integration.

When you finish setting up DocuSign, consider exploring DocuSign Resources and Tips.

Before You Begin

Make sure you have admin access in both your  Agiloft KB and in DocuSign before you begin your setup.

Also, review the two authentication methods below, and select which one you want to set up. The setup steps are listed separately below, so it's best to choose a method before you begin.

• Confidential Authorization Code Grant (ACG) authentication: If your users have their own individual logins for DocuSign, and your workflow supports having users send envelopes in real time, you should probably use this method. ACG is generally simpler to set up, but requires users to have their own accounts and send envelopes themselves, and ACG cannot be used with more than one account simultaneously. For a full list of the advantages and disadvantages of ACG, see the DocuSign documentation here. Note that this page discusses both the confidential and public iterations of ACG authentication, but Agiloft uses Confidential ACG.
  

  To use ACG authentication, you must first go to the DocuSign Accounts table, go to Setup DocuSign Accounts, go to the Layout tab, and add the Integration Key and Secret Key fields to the layout. Click Finish to save your changes.

• JSON Web Token Grant (JWT) authentication: If you use a single login for all users in your integration, or if you need to be able to generate and send envelopes automatically without user input, or if you need to use more than one DocuSign configuration at once, you should probably use this method. JWT is generally more complex to set up, but supports more automated workflows. For a full list of the advantages and disadvantages of JWT, see the DocuSign documentation here.

Creating a DocuSign Account

Before you can set up DocuSign, create a developer account if you don't already have one. You'll use this account for testing purposes during the initial setup. You can create an unlimited number of these accounts.

To set up a free developer account, complete the following steps. When you've completed the set up, you can also follow these same steps to create your production account. 

1. In DocuSign, go to Developer Account > Create Account. 
2. Enter the required details and finish creating an account. This isn't the same as the DocuSign User account you will authenticate later.
3. For JWT authentication:
   1. Click the profile icon in the top right, and then click My Apps and Keys in the drop-down.
   2. In the sidebar under Users and Groups, click Permission Profiles.
   3. Click Actions > View on the DS Admin permission profile to open it.
   4. Go to the User Permissions tab.
   5. Ensure that the "Allow send on behalf of other users through API" check box is selected. If the option is disabled, create a copy of the permission set and then select this option.

Now that you have an account created, you can continue to create an organization and set up authentication.

Configuring DocuSign with ACG

Follow the steps in this section to configure DocuSign with Confidential Authorization Code Grant (ACG) authentication. For JSON Web Token Grant (JWT) authentication, see Configuring DocuSign with JWT.

1. Return to DocuSign and log in with the developer account you created, if you aren't still logged in.
2. Click the profile icon in the top right, and then click My Apps and Keys in the drop-down. 
3. Click Add App and Integration Key.
4. Under General Info, give the integration a name (such as "Agiloft") in the App Name Field, then click Create App.
5. Leave the Authentication setting on Authorization Code Grant.
6. Optionally, under Authentication, select Require Proof Key for Code Exchange (PKCE).
7. Under Authentication, click Add Secret Key.
8. Copy the Secret Key and save it to a safe place where you can access it later.
9. Up in the General Info section, copy the Integration Key and save it in the same place as your Secret Key.
10. Return to the page with your account information and save the API Account ID in the same place as your Secret Key.
11. Add the redirect URI, replacing <server-url> with your KB server address: https://<server-url>/extension/ds/connect/authcode/grant

With the DocuSign account details, you are ready to configure your KB.

1. Log in to your KB as the DocuSign admin user.
2. Briefly, go to the DocuSign Accounts table, open Setup DocuSign Accounts, and go to the Layout tab. Confirm that the layout includes the Integration Method and Secret Key fields, or, if needed, add them to the layout and click Finish to save your changes.
3. Go to Setup > Integration > DocuSign Extension and click Configure.
4. Edit the existing account, or click New to create a new account. Note that you cannot have multiple active DocuSign accounts if you are using ACG authentication with any of them.
5. Give the account a name. If you have multiple accounts listed, make sure the new name specifies what differentiates that account.
6. If you're not using the default Demo server, click Change Server, and select one from the drop-down, and click Set Server.
   
7. Select Authorization Code Grant (ACG) as the Integration Method and provide the API Account ID, Integration Key, and Secret Key.
8. Click Save.
9. You don't need to configure any DocuSign Users in Agiloft, and you can move on to Verifying the KB with DocuSign.

Configuring DocuSign with JWT

Follow the steps in this section to configure DocuSign with JSON Web Token Grant (JWT) authentication. For Confidential Authorization Code Grant (ACG) authentication, see Configuring DocuSign with ACG.

1. Return to DocuSign and log in with the developer account you created, if you aren't still logged in.

2. Click the profile icon in the top right, and then click My Apps and Keys in the drop-down. 
3. Click Add App and Integration Key.
4. Under General Info, give the integration a name (such as "Agiloft") in the App Name Field, then click Create App.
5. Ignore the Authentication setting.
6. Under Service Integration, click Generate RSA. 

7. Copy the Public and Private Keys in their entirety, including the header and footer. Save it to a safe place where you can access it later.

   Be sure to save both Keys to a safe place. You won't be able to view them again, and you'll need them in later steps to complete the setup.
8. If you are using Individual Consent, add a redirect URI. The redirect URI is a splash page or other internal site where the user is sent once they have granted consent for the app. If you like, you can use an Agiloft hosted splash page and set the redirect URI to: https://www.agiloft.com/success/
9. Leave the Additional Settings as they are, and click Save.
10. Save the API Account ID, the Account Base URI, and Integration Key in a convenient and accessible location, just like with your Public and Private Keys.
11. Finally, you need to complete the setup for admin consent, individual consent, or both. Some integrations are set up using a single one of these options, while others may require both. Generally, both consent options are required if not all users have the same domain for their email addresses. You can find more information about these options in DocuSign's documentation here.
    
    1. Admin consent grants consent to every DocuSign User in your domain, simultaneously. This method is usually quicker, and makes it easier to add more users in the future. For integrations that require Admin Consent, complete the Getting Admin Consent section.
    2. Individual consent requires each DocuSign User to grant consent to the API by logging in to confirm permission. This can be used for one main account, or in cases where each user has an individual login, but might use a different domain, such as contractors For integrations that require Individual Consent, complete the Getting Individual Consent section.
    3. For integrations that require both methods, complete both sections.

Granting Admin Consent

To request Admin Consent, you first need to configure an organization in DocuSign using the developer account you created.

1. If you have an existing DocuSign organization that has claimed the domain you'd like to use, follow DocuSign's instructions to Link Administered Accounts to an Organization, and then skip to step 3 below.

2. Otherwise, to create an organization:

   1. Click on Overview on the left menu, then click Get Started in the upper right corner and follow DocuSign's instructions to Create an Organization.

      If you don't see the Get Started button, then DocuSign Admin is not enabled on the account. Contact DocuSign customer support for assistance.

   2. Enter an Organization Name and an optional Description. Click Next.
   3. The account you used to create the organization is automatically linked. Add any other accounts you want to manage centrally, and click Create.
3. Once the Organization is created, you can use the Switch To button to navigate between the eSignature Admin and the DocuSign Admin interfaces. Make sure you're on the DocuSign Admin interface.
4. Navigate to the Connected Apps menu in the Organization Dashboard.
5. Click Authorize Application in the top right corner.
6. Select your app. Under the Permissions field, enter: signature impersonation
7. Click Add. This adds the app to the organization, and grant impersonation for every user. This feature requires that you claim your organization domain before it can become functional.

8. Follow the DocuSign instructions to prove ownership. This will require you to work with your domain admin to make changes to the DNS and CNAME.

   When claiming a domain, ensure that you claim the domain used by the email addresses you use with DocuSign. A domain can only be claimed by one DocuSign organization. If one organization has claimed and verified a domain, then another organization cannot claim it. An organization can claim the same domain in both the demo and production environments.

9. Complete Individual Consent if you plan to use it, or skip to Configuring Your KB.

Getting Individual Consent

To request Individual Consent:

1. Construct the Consent URI based on the below syntax. With values, it will look similar to the Individual Consent URI Sample below.
   

2. For the Base URI value, you'll use https://account-d.docusign.com/oauth/auth when setting up the test environment. When you're switching to production, you'll use https://account.docusign.com/oauth/auth as the Base URI value. This example shows the Base URI used for the test environment and a Redirect URI to an Agiloft splash page:

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=<your_Integration_key>&redirect_uri=https://www.agiloft.com/success/

3. Copy the Consent URI Sample above and replace the <your_Integration_key> value of the Consent URI with the value of your integration key.

4. If you did not use Agiloft's splash page for the Redirect URI in step 4d , replace https://www.agiloft.com/success/ with the value you used in 4d in the sample consent URI.

5. Open the URI in a browser.

6. Log in with your individual account and grant consent for the application.  

7. Provide the link to all users who need to grant individual consent, so they can log in with their individual accounts to also grant consent.

8. Continue to Configuring Your KB.

Configuring Your KB with JWT Authentication

Next, you are ready to configure your KB.

1. Log in to your KB as the DocuSign admin user.
2. Go to Setup > Integration > DocuSign Extension and click Configure.
3. Edit the existing account, or click New to create a new account. You can connect multiple DocuSign accounts with a single KB; this isn't necessary in most cases, but it can useful if you need a separate account to purchase a smaller number of more expensive envelopes in order to avoid higher charges under the primary DocuSign account. Note that you cannot use multiple DocuSign accounts if any of the active accounts are configured to use ACG authentication.
4. Give the account a name. If you have multiple accounts listed, make sure the new name specifies what differentiates that account.
5. Click Change Server. 
6. If you're not using the default Demo server, click Change Server, and select one from the drop-down, and click Set Server.
   
7. Select JWT and provide the API Account ID, Account Base URI, Integration Key, and RSA Private Key. In the RSA Private Key field, include the header and footer.
8. Click Save.

Finally, add user information to your KB.

1. Edit the account again to continue.
2. On the DocuSign Users tab, create a record for the person who will serve as your DocuSign administrator for  Agiloft. This user is able to add and remove users and manage other aspects of the DocuSign setup. The user should have admin rights in both the KB and DocuSign. This should be a new user account, and it's best to create a separate account only for this purpose, rather than assigning a named user. That way, it's easier to transition responsibility internally if needed. To create the user:
   1. Click New.
   2. Use the look-up for the Login or Full Name to find the  Agiloft user. For this first record, select the user you'd like to make the DocuSign Administrator.
   3. If you see an option to choose how to authenticate, select JWT. If you don't see this option, proceed to the next step.

   4. Get the DocuSign User ID by navigating to the User tab in DocuSign, opening the user's profile, and copying the User ID. Then, enter it into the User ID field. For the first user, this should be an admin user account in DocuSign, with the permission profile set to DS Admin.

      In older KBs, this field might not be included in the layout. To make the User ID field visible, open Setup for the DocuSign Users table, go to the Layout tab, and add the User ID field to the layout.

   5. Click Grant Access to DocuSign, then Save and Close the account.
   6. On the DocuSign configuration page, select the new user in the Account Administrator drop-down.

   7. Click Enable DocuSign Connect. If DocuSign is fully enabled, you are returned to the Integration menu and a status notification appears at the top of the page. You can also confirm your connection by clicking Configure again under DocuSign Extension and confirming that a Connect ID now appears. You can now begin testing, or continue on to step 11 to add users.
      

      You might see an error message if the hotlink server URL is set to the localhost by default. To update this value, set the Hotlink Server URL global variable value to your server's domain name. For other issues, consult DocuSign Troubleshooting.

3. Return to DocuSign Users. For each employee who needs to send DocuSign envelopes, follow step 10 to create a DocuSign User entry. When completing step 10d for each user:
   
   • To send envelopes under a user's own DocuSign name, input their DocuSign User ID.

   • To send envelopes under one main account, input the DocuSign Admin User ID for every subsequent user granted access to DocuSign. Make sure that in DocuSign administration, you go to Settings > Users and Groups > Permission Profiles and enable "Allow send on behalf of other users through API" for the admin user's permission profile.

Verifying the KB with DocuSign

For both ACG and JWT authentication, the next step is establishing a connection to DocuSign to verify the account. To verify an account, DocuSign must receive 20 API calls.

To send these calls and establish a connection:

1. Log in as one of the users assigned to the DocuSign account. Typically you can log in as the user assigned to the developer account you created.
2. Create a test Contract record that requires a signature and send it through DocuSign.
3. Repeat step 2 until 20 API calls are registered. You can send the envelopes under a single Contract record to expedite the process.
   

   You can see the amount of API calls on the DocuSign Account Admin dashboard under the Apps and Keys settings, although this number does occasionally take some time to update. Some other API calls that count towards the 20 are granting access to users, or sending and voiding envelopes.

4. Once 20 calls have been completed, go to the Apps and Keys area of DocuSign. Next to the integration key you want to later promote to a production application, select Actions > Start Go-Live Account.
5. In the Request App Review window that appears, select Request Review to start the automatic inspection. After passing this automated review, the key's status changes to Review Passed. 

Going Live with DocuSign

Whether you're going live with DocuSign for the first time, or transitioning from an older integration to a new account, make a plan for the process.

1. If you're transitioning from a previous DocuSign integration, determine a cutover date and communicate it to your users. Make sure they understand that DocuSign will be temporarily unavailable during the cutover window.
2. Log in to the test account at: https://developers.docusign.com/ 
3. Next to the integration key you want to promote, select Actions > Select Go-Live Account.
4. Choose a production account and click Next.
5. In the login window that appears, log in using your production DocuSign account credentials (not your developer account credentials).
6. After logging in, you are prompted to accept the developer terms and conditions. Note that you might need to enable pop-ups in your browser.
7. Next, you are prompted to select a production account to promote the key. Depending on your internal setup, there may be one or many accounts to choose from. Choose the account that contains the DocuSign users who will also be Agiloft users.

Configuring your Production Account

Once your app has been verified:

1. Log in to your Production account in DocuSign at: https://account.docusign.com/

2. The integration key promoted from the development account appears in the Apps and Keys section of your Production DocuSign account. Next to the key, select Actions > Edit.

3. Repeat the configuration steps for ACG or JWT to generate keys and, for JWT, grant user consent with the new account.

4. Return to Agiloft and log in as the DocuSign administrator you assigned earlier.
5. Reintegrate the KB with DocuSign:
   1. First, disable DocuSign Connect. To do so, go to Setup > Integration > DocuSign Extension and click Configure, then click Disable DocuSign Connect.
   2. Click Remove Access to remove current DocuSign users, then ignore the warning and save your changes. If you don't remove user access, you will be unable to change the server in the next step.

   3. Change the server from the developer Account Base URI to match your production Account Base URI. Click Set Server to apply the change.

   4. Complete the account details with the updated keys:
      • For ACG, provide the API Account ID, Integration Key, and Secret Key.
      • For JWT, provide the API Account ID, Account Base URI, Integration Key, and RSA Private Key. In the RSA Private Key field, include the header and footer.
   5. For JWT only, go to the DocuSign Users tab, create or select your DocuSign Admin account as a user, and then select them as Account Administrator.
      1. Enter their production User ID and Grant access again under DocuSign Users section.
      2. Scroll back up and set them as Account Administrator. 
   6. Click Save and then edit the account again to continue.

6. Click Enable DocuSign Connect. If DocuSign is successfully enabled, you are returned to the Integration menu and a status notification appears at the top of the page. You can also confirm your connection by clicking Configure again under DocuSign Extension and confirming that a Connect ID now appears. You can now begin testing, or continue on to step 11 to add users.

   You might see an error message if the hotlink server URL is set to the localhost by default. To update this value, set the Hotlink Server URL global variable value to your server's domain name. For other issues, consult DocuSign Troubleshooting.

7. For JWT only, edit the DocuSign users from step 5. Replace the existing DocuSign User ID with the user ID from the production account, and grant access to DocuSign again.
8. Finally, create a new contract and test it by sending it out for signature.

Customizing the Create DocuSign Envelope Action

The optional final step is to customize the Create DocuSign Envelope action. This option is useful if you need to change the default attributes about the Create DocuSign Envelope used to create and send out DocuSign envelopes. Some customizable attributes are: 

• The total number of signers
• Which DocuSign templates to use
• Which attached file field holds the documents
• The subject line for the DocuSign email to recipients

To configure the Create DocuSign Envelope action, follow the steps below.

1. Go to Setup > Integration, click Configure under DocuSign Extension, and edit the account.
   • To edit an existing action, locate the Action drop-down menu, select Create DocuSign Envelope, and click Edit Action.
   • To create a new DocuSign Envelope action for a table, locate the Table drop-down menu, select the table from the list, and click Add Action. When you create a new action, you must also also add a Name and Description for the action.
2. Complete the fields to configure the action.
   
3. Click the Recipients tab and complete the fields for each recipient. At the top, specify how many people will receive the envelope. Then, for each recipient in the sending order, configure the Role Name (defined in the DocuSign Roles table), Role, Recipient Field, optional Access Code, and message contents.
   
4. Click Save. 

This completes the setup. For more information about using DocuSign, consult the DocuSign Resources and Tips pages.