IAM SDK - TypeScript (beta)

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 TypeScript 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 project is by installing the @docusign/iam-sdk package using your preferred package manager.

Adding the TypeScript SDK to your project using the command line

Run the following command to install the SDK and add it to your project dependencies:

npm install @docusign/iam-sdk

To install a specific version, append the version number to the package name:

npm install @docusign/iam-sdk@1.0.0-beta.3

This will automatically update your package.json file and download the SDK and its dependencies into your node_modules directory.

Adding the TypeScript SDK to your project using your project’s package.json file

Alternatively, you can manually add the dependency by editing your package.json file:

"dependencies": {
  "@docusign/iam-sdk": "1.0.0-beta.3"
}

Then run your package manager’s install command:

npm install

Getting started with the TypeScript IAM SDK

The best way to learn how to use the TypeScript IAM SDK is to explore the code examples provided by Docusign. You can find the TypeScript code examples in the code-examples-node 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 TypeScript 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, AuthUtils.DOCUSIGN_IAM_OAUTH_SCOPES 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.

import { AuthUtils, IamClient } from '@docusign/iam-sdk';
// Details configured from the Docusign developer console.
const clientId = process.env.AUTH_CODE_CONFIDENTIAL_CLIENT_ID!;
const secretKey = process.env.AUTH_CODE_CONFIDENTIAL_SECRET_KEY!;
const redirectUri = process.env.DOCUSIGN_REDIRECT_URI!;
const authorizationUrl = AuthUtils.createAuthorizationUrl({
  type: "code",
  clientId,
  redirectUri,
  scopes: AuthUtils.DOCUSIGN_IAM_OAUTH_SCOPES,
});
// Prompt the user to visit the authorization URL. They'll need to grab
// the code from the `code` query parameter
console.log(
  `Please visit this URL to authorize the application:\n${authorizationUrl}\n`,
);

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. This example shows the Confidential Authorization Code Grant flow. You can find examples for other supported flows in the SDK repository, including:

• Authorization Code (public)
• Implicit Grant
• JWT Grant

// Get token information using the authorization code
const { accessToken, refreshToken, expiresIn } = await new IamClient().auth
  .getTokenFromConfidentialAuthCode({ clientId, secretKey }, { code })
  .catch((error) => {
    if (error instanceof OAuthErrorResponse) {
      throw new Error(
        `Failed to get auth session. Error: ${error.error}, Description: ${error.errorDescription}`,
      );
    }
    throw error;
  });
console.log(
  `Auth Session:\n${JSON.stringify({ accessToken, refreshToken, expiresIn }, null, 2)}\n`,
);

Using an access token

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

const authenticatedClient = new IamClient({
  accessToken: accessToken,
});
const result = await authenticatedClient.auth.getUserInfo();

Open source repository

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

Compatibility

The TypeScript IAM SDK requires Node.js version 18 or above. See RUNTIMES.md for more information.

Note: Node v18 is deprecated and may be unsupported in future SDK releases. Use Node v20 or later when possible.

Code examples

You can find code examples showcasing how to use the IAM SDK with Agreement Builder API, Connected Fields API, and Agreement Manager API in the code-examples-node 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.