> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Node.js SDK authentication

## Obtaining an access token

The goal of [authentication](/docs/esign-rest-api/esign101/auth) is to obtain an access token. An access token is needed for every API call to Docusign. Access tokens last from one to eight hours, depending on the grant type used to obtain the access token.

## Determining your OAuth flow

Please review the [Platform Authentication 101](/platform/auth) documentation on the Developer Center to determine which OAuth flow to use.

## Authorization Code Grant with Node.js

Because the [OAuth Authorization Code Grant](/platform/auth/authcode) flow is centered on interactions between the user and the identity server via the browser, the SDK is not used.

### Configuration information required to proceed with Authorization Code Grant

* **Integration key** (client ID): This can be obtained in your developer account by accessing the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. See the [Docusign eSignature Admin Guide](https://support.docusign.com/guides/ndse-admin-guide-api-and-keys) for more information.
* **Client secret**: This is for the integration key you obtained above. It is also created on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. The client secret can only be copied the first time it is displayed; it will not be visible later. Make sure to retain it for your records. If you forget your client secret, you can generate a new one to use.
* **Redirect/Callback URI**: This is the URI to which the end user will be redirected when your application uses the Authorization Code Grant flow. The URI must exactly match one of the redirect URIs you defined for your integration key on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. You can add multiple redirect URIs for a single integration key.

Authorization Code Grant requires a web interface because users must utilize the Docusign Identity Provider (IdP) to authenticate with their Docusign account. In this section, we’ll cover the recommended practices for using Authorization Code Grant in your Node.js application. Other Node.js web technologies may require a different technique to complete the Authorization Code Grant flow and are beyond the scope of this guide.

### Using Authorization Code Grant in your Node.js application

In your client, you can instantiate an OAuth object to enable the Docusign Authorization Code Grant flow to work with your application. You can find a full working example in our [GitHub repository](https://github.com/docusign/docusign-esign-node-client/blob/master/test/SdkUnitTests.js#L164).

```text
apiClient.generateAccessToken(IntegratorKeyAuthCode, ClientSecret, code)
  .then(function(oAuthToken){
    assert.equal(err, undefined);
    assert.notEqual(oAuthToken, undefined);
    assert.notEqual(oAuthToken.accessToken, undefined);
    assert.ok(oAuthToken.expiresIn > 0);

    console.log(oAuthToken);

    apiClient.getUserInfo(oAuthToken.accessToken)
      .then(function(userInfo){
        assert.equal(err, undefined);
        assert.notEqual(userInfo, undefined);
        assert.notEqual(userInfo.accounts, undefined);
        assert.ok(userInfo.accounts.length > 0);

        console.log("UserInfo: " + userInfo);
        // parse first account's basePath
        // below code required for production, no effect in demo (same
        // domain)
        apiClient.setBasePath(userInfo.accounts[0].baseUri + "/restapi");
        return done(oAuthToken)

      })
      .catch(function(err){
        return done(err);
      });
  })
  .catch(function(err){
    return done(err);
  });
});
```

## JSON Web Tokens (JWT) with Node.js

Every Node.js SDK (eSignature as well as others) includes two JWT Grant functions:

[requestJWTUserToken](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L1153): This function uses the JWT Grant flow to request a token that will represent a specific user. This JWT Grant flow is used for all eSignature REST API methods and for most other Docusign API methods as well.

[requestJWTApplicationToken](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L1180): This function uses the JWT Grant flow to request a token that will represent the application itself (not a user). This JWT Grant flow is useful for specific Docusign partners who are part of special Docusign programs allowing them to manage accounts using the [Docusign Admin API](/docs/admin-api).

### Configuration information required to proceed with JWT

* **Integration key (client ID)**: This can be obtained in your developer account from the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. See the [Docusign eSignature Admin Guide](https://support.docusign.com/guides/ndse-admin-guide-api-and-keys) for more information.

* **RSA private key**: This is for the integration key you obtained above and can also be created on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. You only need the private key, and it can only be copied once. Make sure to retain it for your records.

* **Base path**: To use either JWT Grant function, you need to use an SDK `ApiClient` object. To create an `ApiClient` object, you need to provide a base path. Since the application’s correct base path is not yet known, use placeholder values to indicate which system should be queried:

* `https://demo.docusign.net/restapi # development`

* `https://www.docusign.net/restapi # production`

**Note:** This placeholder base path is used only for the `ApiClient` [requestJWTUserToken](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L1153), [requestJWTApplicationToken](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L1180), and [getUserInfo](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L967) functions. Once you make these calls, you should be able to get the correct base path and use it to make all other API calls.

* **Impersonated User ID (UserID)**: This is a GUID identifying the Docusign user that you will be impersonating with the access token. Your own **User ID** can be found at the top of the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page.

User IDs for other members of your account can be looked up on the [Users](https://admindemo.docusign.com/authenticate?goTo=users) page. Locate the user in the list; then use the **Actions > Edit** button to open the user’s **Profile** page. The user’s user ID is shown on the page as the **User ID** value.

User IDs can also be looked up programmatically by using the [Users:list](/docs/esign-rest-api/reference/users/users/list) method. It requires administrative permissions.

This parameter is not used for the [requestJWTApplicationToken](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L1180) function.

* **Scopes**: These represent the OAuth scopes (permissions) that are being requested. For eSignature REST API methods, use the `signature` scope. The `impersonation` scope is implied by the JWT Grant operation and does not need to be included. If the access token will be used for other Docusign APIs, additional scopes may be required; see each API’s [authentication](/docs/esign-rest-api/esign101/auth) requirements.

* **Parameter formats and additional parameters** are documented in [Node.js SDK Reference](https://docusign.github.io/docusign-esign-node-client/).

User IDs for everyone in your account are available on the account administrator’s [Users](https://admindemo.docusign.com/authenticate?goTo=users) page.

[JWT Grant](/platform/auth/jwt/jwt-get-token) enables developers to obtain OAuth access tokens without requiring users to log in, given that they have already [provided consent](https://www.docusign.com/blog/developers/oauth-jwt-granting-consent) for the application to impersonate them when making API calls.

To use JWT from the Node.js SDK, make the following call (you can find this code in [GitHub](https://github.com/docusign/code-examples-node/blob/master/lib/DSJwtAuth.js#L86)):

```text
    const results = await dsApi.requestJWTUserToken(dsConfig.dsClientId, dsConfig.impersonatedUserGuid, this.scopes, rsaKey, jwtLifeSec);
```

Best practices for managing access tokens:

* Do cache the access token until it expires or is about to expire.
* Do not create a new access token for each API call.
* Recommended: Check the expiration time of the access token before you use it. If it has expired or is about to expire (within 10 minutes), then obtain a new authorization token before making the API call. If using a refresh token, check that it hasn’t expired as well.

## Obtaining user information

Once authenticated, you need information about the access token’s user. That information is required to make future API calls. Moreover, it’s possible that the user is a member of more than one Docusign account. In this scenario, you can obtain all accounts associated with this user to enable them to pick which Docusign account they wish to use with the integration.

The recommended practice (frequently used by Docusign apps) is to use the user’s default account and let them change to use a different account.

The recommended practice from the partner group is to include the `accountId` as a configuration value since the API application may require specific account settings. In this case, the app should check that the user has access to the configured `accountId`.

The Node.js code to retrieve the [user information](/platform/auth/reference/user-info) from the developer account is:

```text
    const results = await dsApi.getUserInfo(this.accessToken);
```

The [getUserInfo](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L967) function returns a [UserInfo](https://github.com/docusign/docusign-esign-node-client/blob/master/src/oauth/UserInfo.js) object that has various pieces of information related to the user. The [accounts](https://github.com/docusign/docusign-esign-node-client/blob/master/src/oauth/UserInfo.js#L66) property is a list of [Account](https://github.com/docusign/docusign-esign-node-client/blob/master/src/oauth/Account.js) objects that provides the collection of Docusign accounts and their information. You can use the `isDefault` property of the `Account` object to check if this is the user’s default account. The `UserInfo` object also includes `name` and `email` properties related to the logged-in user.

The `Account` object also includes the `baseUri` property. The `baseUri` property forms the first term of the URL you must use to make API calls on behalf of the user’s account. Since each Docusign account is associated with a specific Docusign data center, the `baseUri` property includes the data center’s designation, such as na2.docusign.net or eu.docusign.net, e.g., . The `baseUri` property’s value is concatenated with the string “/restapi” to form the base path, which represents the root of the URL for all endpoints in the eSignature REST API, e.g., .

When you instantiate the `ApiClient` object, which is used to make API calls, you pass the value of the base path in its constructor (see below). If you reuse an `ApiClient` object, use its [setBasePath](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L250) function to ensure the correct base path is set.

## Instantiating and configuring the ApiClient for making API calls

The `ApiClient` module represents the base object used as a starting point for all eSignature API calls. You will have to instantiate this object in your code before you can proceed to make API calls.

The basic flow of instantiating an `ApiClient` looks like this:

```text
    let dsApiClient = new docusign.ApiClient();
    dsApiClient.setBasePath(args.basePath);
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + args.accessToken);
    let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
```

Let’s break down these four lines of code to understand them better.

### Instantiating the ApiClient object

```text
    let dsApiClient = new docusign.ApiClient();
```

This line is used to instantiate a new `ApiClient` object. This object is used to make eSignature API calls to Docusign.

### Setting the base path

```text
    dsApiClient.setBasePath(args.basePath);
```

This `basePath` parameter tells the SDK the first part of the URL to use when making API calls. The latter part of the URL is determined in each API call by the specific functions you choose to use.

The base path for the developer (demo) environment is . The base path for the production environment depends on the specific data center where your account is provisioned.

The base path for the eSignature REST API consists of the name of the data center (demo, na2, na3, eu1, ca, au, etc.) and then .docusign.net/restapi.

### Setting the HTTP header with an authentication token

```text
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + args.accessToken);
```

This line is used to provide the authentication information required to make API calls. You first need to obtain a valid access token for authentication. You can find out how to obtain a token from the how-to topics for [Authorization Code Grant](/platform/auth/authcode/confidential-authcode-get-token), [Implicit Grant](/platform/auth/implicit/implicit-get-token), and [JWT Grant](/platform/auth/jwt/jwt-get-token).

[defaultHeaders](https://github.com/docusign/docusign-esign-node-client/blob/master/src/ApiClient.js#L185) is a JavaScript object that is used to provide additional HTTP headers for API requests. You can add additional headers with API calls that use the `ApiClient` object. The `"Authorization"` header is used to provide the authentication information for the request. The token is added after the word `"Bearer"`, provided in the `accessToken` variable. This only needs to be done once for all API calls that will be utilizing the same `ApiClient` object; however, the token is only valid for eight hours. You will need to obtain a new one and update this header when the token expires.

### Instantiating the required object for the specific set of API calls

```text
    let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
```

This is an example of how to use the `ApiClient` object. It is used as a parameter on the constructors of all the API modules. By instantiating the `EnvelopesApi` module to use the preconfigured `ApiClient`, you are ready to make API calls.