IAM SDK - Java (beta) | Docusign

The Docusign Intelligent Agreement Management (IAM) SDKs assist developers in using the Intelligent Agreement Management (IAM) APIs, simplifying common tasks.

This page offers high-level information about the Java SDK and its usage.

APIs included in this SDK

The IAM SDKs include the following APIs:

Workflow Builder API: Trigger and manage Agreement Builder workflows from your own app.
Agreement Manager API: Connect AI-extracted data from agreements stored in Agreement Manager into your own app. into your own app.
Workspaces API: Create structured, secure, and scalable agreement workflows.
Connected Fields API: Discover extension apps that your app can use to validate input as part of the eSignature process.

Additional APIs may be added later; check this page for updates.

How to obtain the SDK

The easiest way to add the SDK to your Java project is by including the iam-sdk dependency using your preferred build tool.

Adding the Java SDK to your project using Gradle

Add the following line to your build.gradle file inside the dependencies block:

implementation 'com.docusign:iam-sdk:1.0.0-beta.4'

To use a different version, simply update the version number in the string.

After saving your changes, run:

./gradlew build

This will download the SDK and its dependencies into your local Gradle cache and make them available to your project.

Adding the Java SDK to your project using Maven

Add the following to your project’s pom.xml files inside the <dependencies> section:

<dependency>
    <groupId>com.docusign</groupId>
    <artifactId>iam-sdk</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>

To use a different version, adjust the <version> tag accordingly.

After updating your pom.xml, run the following command to install the dependencies:

mvn install

This will fetch the SDK and its dependencies into your local Maven repository.

Getting started with the Java IAM SDK

The best way to learn how to use the Java IAM SDK is to explore the code examples provided by Docusign. You can find the Java code examples in the code-examples-java public GitHub repository. These code examples can also be part of the ZIP file downloaded when you use the Quickstart tool. This tool will also create all the necessary configuration data in your developer account so you’ll be ready to run it.

Authentication support

Every API call must be authenticated. The Java IAM SDK provides functionality to simplify the use of authentication for making IAM API calls.

Obtaining an access token

Before you begin the authentication process, you must create and configure your app. Specifically:

Create your app and obtain your integration key (client ID).
Generate a client secret for your app.
Add your redirect URI to the list of allowed redirect URLs associated with your integration Key.

These settings are required to obtain an authorization code and exchange it for an access token in the steps below, which demonstrate the Confidential Authorization Code Grant flow. Other OAuth flows may require different configuration settings.

Step 1: Obtain an authorization code

To call the DocuSign IAM APIs, you must request the appropriate OAuth scopes. The SDK provides predefined constants for common scope sets. For example, AuthScope.getAllScopes() includes all scopes used across the IAM SDK. You can use these helpers or supply your own array of scopes.

If this is the first time this application is requesting an authorization code from this user, the user will be asked to provide consent. Docusign will then redirect them to your specified redirect URI with an authorization code included as a query parameter named code.

Java

import com.docusign.iam.sdk.models.components.OAuthBasePath;
import com.docusign.iam.sdk.models.components.OAuthResponseType;
import com.docusign.iam.sdk.models.components.AuthScope;
import com.docusign.iam.sdk.utils.auth.AuthorizationUrlBuilder;
// Create the authorization URL
String consentUrl = AuthorizationUrlBuilder.builder()
    .basePath(OAuthBasePath.DEMO)
    .responseType(OAuthResponseType.CODE)
    .clientId(System.getenv("DOCUSIGN_CLIENT_ID"))
    .redirectUri(System.getenv("DOCUSIGN_REDIRECT_URI"))
    .addScopes(AuthScope.getAllScopes())
    .build();
// Direct the user to grant consent
System.out.println("Please visit the following URL to authorize the application: " + consentUrl);

Step 2: Exchange an authorization code for an access token

After you obtain the authorization code, you need to use it to get an access token. The SDK provides helper functions to simplify this process. The example below shows the Confidential Authorization Code Grant flow. You can find examples for other supported flows in the SDK repository, including:

Java

import java.util.Scanner;
import com.docusign.iam.sdk.IamClient;
import com.docusign.iam.sdk.models.components.ConfidentialAuthCodeGrantRequestBody;
import com.docusign.iam.sdk.models.operations.GetTokenFromConfidentialAuthCodeResponse;
import com.docusign.iam.sdk.models.operations.GetTokenFromConfidentialAuthCodeSecurity;
try {
  // Prompt user for the authorization code
  Scanner scanner = new Scanner(System.in);
  System.out.print("Enter the authorization code from the redirect URL: ");
  String authCode = scanner.nextLine();
  // Create an unauthenticated client to exchange the auth code for a token
  IamClient anonClient = IamClient.builder().build();
  // Prepare the request with the auth code
  ConfidentialAuthCodeGrantRequestBody request = ConfidentialAuthCodeGrantRequestBody.builder()
    .code(authCode)
    .build();
  // Get token using client credentials
  GetTokenFromConfidentialAuthCodeResponse res = anonClient.auth().getTokenFromConfidentialAuthCode()
    .security(GetTokenFromConfidentialAuthCodeSecurity.builder()
      .clientId(System.getenv("DOCUSIGN_CLIENT_ID"))
      .secretKey(System.getenv("DOCUSIGN_CLIENT_SECRET"))
      .build())
    .request(request)
    .call();
  String accessToken = res.authorizationCodeGrantResponse().get().accessToken();
  System.out.println("Access Token: " + accessToken);
} catch (OAuthErrorResponse e) {
  System.out.println("OAuth Error: " + e.getMessage());
}

Using an access token

Once you have obtained an access token, you can use it to make API calls this way:

Java

import com.docusign.iam.sdk.IamClient;
// Initialize the SDK with your access token
IamClient sdk = IamClient.builder()
    .accessToken(accessToken)
    .build();
// Make API calls on behalf of the user
var userInfo = sdk.auth().getUserInfo().call();
System.out.println("User Info: " + userInfo);

Open source repository

The source being used to build the Java IAM SDK is available publicly in the following repository on our public GitHub: https://github.com/docusign/docusign-iam-java-client. You can use it to build your own version of the SDK.

Compatibility

The Java IAM SDK requires JDK 11 or later.

Code examples

You can find code examples showcasing how to use the IAM SDK with Maestro API, Connected Fields API, and Navigator API in the code-examples-java repo.

Providing feedback about the SDK

To provide feedback on the SDK, please either submit an issue in the GitHub repository or send an email to developers@docusign.com.