GitHub repo: code-examples-java
This GitHub repo includes code examples for the DocuSign Admin API, Click API, eSignature REST API, Monitor API, and Rooms API. To switch between API code examples, in the application.json file, modify the DS_API_NAME setting from ESIGNATURE to ADMIN, CLICK, MONITOR, or ROOMS.
This repo is a Java Spring Boot application that supports the following authentication workflows:
-
Authentication with DocuSign via Authorization Code Grant. When the token expires, the user is asked to re-authenticate. The refresh token is not used.
-
Authentication with DocuSign via JSON Web Token (JWT) Grant. When the token expires, it updates automatically.
The Spring Boot security Oauth2 boot autoconfigure package is used for authentication.
The OAuth library is used in the file WebSecurityConfig.java.
For more information about the scopes used for obtaining authorization to use the eSignature API, see Required scopes.
For a list of code examples that use the eSignature API, select the Java tab under Examples and languages on the DocuSign Developer Center.
Note: To use the Rooms API, you must also create your Rooms developer account. Examples 4 and 6 require that you have the DocuSign Forms feature enabled in your Rooms for Real Estate account.
For more information about the scopes used for obtaining authorization to use the Rooms API, see Required scopes.
For a list of code examples that use the Rooms API, select the Java tab under Examples and languages on the DocuSign Developer Center.
For more information about the scopes used for obtaining authorization to use the Click API, see Required scopes
For a list of code examples that use the Click API, select the Java tab under Examples and languages on the DocuSign Developer Center.
Note: To use the Monitor API, you must also enable DocuSign Monitor for your organization.
For information about the scopes used for obtaining authorization to use the Monitor API, see the scopes section.
For a list of code examples that use the Click API, select the Java tab under Examples and languages on the DocuSign Developer Center.
Note: To use the Admin API, you must create an organization in your DocuSign developer account. Also, to run the DocuSign CLM code example, CLM must be enabled for your organization.
For information about the scopes used for obtaining authorization to use the Admin API, see the scopes section.
For a list of code examples that use the Admin API, select the Java tab under Examples and languages on the DocuSign Developer Center.
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip items 1 and 2 as they were automatically performed for you.
-
A free DocuSign developer account; create one if you don't already have one.
-
A DocuSign app and integration key that is configured to use either Authorization Code Grant or JWT Grant authentication.
This video demonstrates how to obtain an integration key.
To use Authorization Code Grant, you will need an integration key and a secret key. See Installation steps for details.
To use JWT Grant, you will need an integration key, an RSA key pair, and the API Username GUID of the impersonated user. See Installation steps for JWT Grant authentication for details.
For both authentication flows:
If you use this launcher on your own workstation, the integration key must include redirect URIs of
If you host this launcher on a remote web server, set your redirect URI as
{base_url}/login
where {base_url} is the URL for the web app.
-
Download JDK 11 or later and extract to C:\Program Files\Java
-
Download Maven and extract to C:
- Follow these instructions to add both Java and Maven to the
PATHenvironment variable.
- Follow these instructions to add both Java and Maven to the
-
Git Bash command line, macOS Terminal, or Linux shell
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 4 as it was automatically performed for you.
- Extract the Quickstart ZIP file or download or clone the code-examples-java repository.
- In your command-line environment, switch to the folder:
cd <Quickstart folder>orcd code-examples-java - Package the code:
mvn package - To configure the launcher for Authorization Code Grant authentication, create a copy of the file src/main/resources/application.example.json and save the copy as src/main/resources/application.json.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
DS_TARGET_ACCOUNT_ID. - Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in application.json as your
authorization.code.grant.client.client-id. - Generate a secret key, if you don’t already have one. Under Authentication, select + ADD SECRET KEY. Copy the secret key and save it in application.json as your
authorization.code.grant.client.client-secret. - Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/login&type=acg. Select SAVE.
- Set a name and email address for the signer. In application.json, save an email address as
DS_SIGNER_EMAILand a name asDS_SIGNER_NAME.
Note: Protect your personal information. Please make sure that application.json will not be stored in your source code repository.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
- Run the launcher:
java -Dspring.profiles.active=dev -jar target/code-examples-java-1.0-SNAPSHOT.war
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 4 as it was automatically performed for you.
Also, in order to select JSON Web Token authentication in the launcher, in src/main/resources/application.json, change the quickstart setting to false.
- Extract the Quickstart ZIP file or download or clone the code-examples-java repository.
- In your command-line environment, switch to the folder:
cd <Quickstart folder>orcd code-examples-java - Package the code:
mvn package - To configure the launcher for JWT Grant authentication, create a copy of the file src/main/resources/application.example.json and save the copy as src/main/resources/application.json.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
DS_TARGET_ACCOUNT_IDand as yourjwt.grant.client.impersonated-user-guid. - Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in application.json as your
jwt.grant.client.client-id. - Generate an RSA key pair, if you don’t already have one. Under Authentication, select + GENERATE RSA. Copy the private key, and save it in a new file named src/main/resources/private.key.
- Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/login&type=jwt. Select SAVE.
- Set a name and email address for the signer. In application.json, save an email address as
DS_SIGNER_EMAILand a name asDS_SIGNER_NAME.
Note: Protect your personal information. Please make sure that application.json will not be stored in your source code repository.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
- Run the launcher:
java -Dspring.profiles.active=dev -jar target/code-examples-java-1.0-SNAPSHOT.war
The launcher automatically opens. - On the black navigation bar, select Login.
- From the picklist, select JSON Web Token (JWT) grant > Authenticate with DocuSign.
- When prompted, log in to your DocuSign developer account. If this is your first time using the app, select ACCEPT at the consent window.
- Select your desired code example.
IntelliJ IDEA can be used with the launcher. The IntelliJ IDEA Ultimate edition is required due to its support for Spring Boot and JSP view pages.
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 2 as it was automatically performed for you.
- Extract the Quickstart ZIP file or download or clone the code-examples-java repository.
- To configure the launcher for Authorization Code Grant authentication, create a copy of the file src/main/resources/application.example.json and save the copy as src/main/resources/application.json.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
DS_TARGET_ACCOUNT_ID. - Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in application.json as your
authorization.code.grant.client.client-id. - Generate a secret key, if you don’t already have one. Under Authentication, select + ADD SECRET KEY. Copy the secret key and save it in application.json as your
authorization.code.grant.client.client-secret. - Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/login&type=acg. Select SAVE.
- Set a name and email address for the signer. In application.json, save an email address as
DS_SIGNER_EMAILand a name asDS_SIGNER_NAME.
Note: Protect your personal information. Please make sure that application.json will not be stored in your source code repository.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
- Start IntelliJ IDEA Ultimate. In the Welcome to IntelliJ IDEA dialog box, select Open.
- In the Open File or Project dialog box, select your Quickstart folder or code-examples-java, then select OK.
- In Open or Import Project dialog box, select Maven project, then select OK.
- Create a Java application configuration: In the top navigation bar, select Run > Edit configurations.
- In the far left corner, select + > Spring Boot.
- To the right of Main class, select ... > App (com.docusign) code-examples-java, then select OK.
- Under Spring Boot, select the Enable debug output checkbox, then select OK.
- Run the launcher: In the top navigation bar, select Run > Run 'App'. The launcher automatically opens.
When prompted, log in to your DocuSign developer account. If this is your first time using the app, select ACCEPT at the consent window. - [Optional] To install Lombok, select File > Settings > Plugins > Marketplace tab. To the right of the magnifying glass icon, input:
Lombok
It should have an author named Michail Plushnikov. Select Install, then restart IntelliJ.
Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 2 as it was automatically performed for you.
-
Extract the Quickstart ZIP file or download or clone the code-examples-java repository.
-
To configure the launcher for Authorization Code Grant authentication, create a copy of the file src/main/resources/application.example.json and save the copy as src/main/resources/application.json.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
DS_TARGET_ACCOUNT_ID. - Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in application.json as your
authorization.code.grant.client.client-id. - Generate a secret key, if you don’t already have one. Under Authentication, select + ADD SECRET KEY. Copy the secret key and save it in application.json as your
authorization.code.grant.client.client-secret. - Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/login&type=acg. Select SAVE.
- Set a name and email address for the signer. In application.json, save an email address as
DS_SIGNER_EMAILand a name asDS_SIGNER_NAME.
Note: Protect your personal information. Please make sure that application.json will not be stored in your source code repository.
- Add your API Username. On the Apps and Keys page, under My Account Information, copy the API Username GUID and save it in application.json as your
-
Open Eclipse and select File > Import. In the Import dialog box, select Existing Maven Project > Next > Browse, browse for your Quickstart folder or code-examples-java, then Select Folder.
- Under Projects, the
pom.xmlfile should be selected. - To save the project link to your Eclipse workspace, select the Add project(s) to working set checkbox. Select Finish.
- Under Projects, the
-
Next, select Run, then Run Configurations, and right-click Maven Build, then New Configuration to clean and compile the package.
- In the Name field, input:
build - In Base directory, input:
${workspace_loc:/code-examples-java} - In Goals, input:
clean package - Select the JRE tab. Under Runtime JRE, ensure it lists jdk-11 or higher. Select Apply to save.
- In the Name field, input:
-
In the Run Configurations dialog box, in the left sidebar, right-click Java Application, then select New Configuration.
- In the Name field, input:
App - In the Project field, input:
code-examples-java - In the Main class field, input:
com.docusign.App - Select the JRE tab. Under Runtime JRE, ensure it lists jdk-11 or higher. Select Apply to save.
- Select Run to run the launcher. The launcher automatically opens.
When prompted, log in to your DocuSign developer account. If this is your first time using the app, select ACCEPT at the consent window.
- In the Name field, input:
-
[Optional] Download lombok.jar to your local machine, then run the following command to install Lombok:
java -jar lombok.jar
To use the payments code example, create a test payment gateway on the Payments page in your developer account. See Configure a payment gateway for details.
Once you've created a payment gateway, save the Gateway Account ID GUID to application.json.
This repository uses the MIT License. See LICENSE for details.
Pull requests are welcomed. Pull requests will only be considered if their content uses the MIT License.