Bash Launcher Code Examples

GitHub repo: code-examples-bash

This GitHub repo includes code examples for the DocuSign Admin API, Click API, eSignature REST API, ID Evidence API, Monitor API, Notary API, and Rooms API. To switch between API code examples, select the desired option from the menu when prompted.

Introduction

This repo is a collection of Bash scripts that support 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.

eSignature REST API

For more information about the scopes used for obtaining authorization to use the eSignature REST API, see Required scopes.

For a list of code examples that use the eSignature REST API, see the How-to guides overview on the DocuSign Developer Center.

Admin API

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, see the How-to guides overview on the DocuSign Developer Center.

Click API

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, see the How-to guides overview on the DocuSign Developer Center.

ID Evidence API

Note: To run the ID Evidence code examples, you must first complete the Prerequisites.

For more information about the scopes used for obtaining authorization to use the ID Evidence API, see Required scopes.

For a list of code examples that use the ID Evidence API, see the How-to guides overview on the DocuSign Developer Center.

Maestro API (beta)

Note: Maestro API is currently only avaiable for developers that participate in the beta program.

For information about the scopes used for obtaining authorization to use the Maestro API, see the scopes section.

For a list of code examples that use the Maestro API, see the How-to guides overview on the DocuSign Developer Center.

Monitor API

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 Monitor API, see the How-to guides overview on the DocuSign Developer Center.

Notary API (closed beta)

Note: For closed beta participants interested in adding Notary API functionality to your production account, contact your DocuSign representative.

Example 1 requires a Sender DocuSign developer account API account ID that has been provisioned for the Notary API base URI.

Example 2 requires that you create an organization in your Sender DocuSign developer account.

For information about the scopes used for obtaining authorization to use the Notary API, see the scopes section.

For a list of code examples that use the Notary API, see the How-to guides overview on the DocuSign Developer Center.

Rooms API

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, see the How-to guides overview on the DocuSign Developer Center.

Web Forms API

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact DocuSign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

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 Web Forms API, see the How-to guides overview on the DocuSign Developer Center.

Installation

Prerequisites

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.

1. A free DocuSign developer account; create one if you don't already have one.

2. A DocuSign app and integration key that is configured for authentication to use either Authorization Code Grant or JWT Grant.

   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 User ID 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 a redirect URI of

   http://localhost:8080/authorization-code/callback

   If you host this launcher on a remote web server, set your redirect URI as

   {base_url}/authorization-code/callback

   where {base_url} is the URL for the web app.

3. Git Bash command line, macOS Terminal, or Linux shell

4. For Authorization Code Grant authentication PHP 8.0.0 is required. For JWT Grant authentication, PHP 8.0.0 and Python 3 are required.

Installation steps

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 3 as it was automatically performed for you.

1. Extract the Quickstart ZIP file or download or clone the code-examples-bash repository.
2. In your command-line environment, switch to the folder:
   cd <Quickstart folder name> or cd code-examples-bash
3. To configure the launcher for Authorization Code Grant authentication, create a copy of the file config/settings.example.txt and save the copy as config/settings.txt.
   1. 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 settings.txt as your INTEGRATION_KEY_AUTH_CODE.
   2. 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 settings.txt as your SECRET_KEY.
   3. Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/authorization-code/callback. Select SAVE.
   4. Set a name and email address for the signer. In settings.txt, save an email address as SIGNER_EMAIL and a name as SIGNER_NAME.
      Note: Protect your personal information. Please make sure that settings.txt will not be stored in your source code repository.
4. Run the launcher: bash launcher.sh
5. Select an API when prompted.
6. Select Authorization Code Grant when authenticating your account.
7. Select your desired code example.

Installation steps for JWT Grant authentication

Note: If you downloaded this code using Quickstart from the DocuSign Developer Center, skip step 3 as it was automatically performed for you.

1. Extract the Quickstart ZIP file or download or clone the code-examples-bash repository.
2. In your command-line environment, switch to the folder:
   cd <Quickstart folder name> or cd code-examples-bash
3. To configure the launcher for JWT Grant authentication, create a copy of the file config/settings.example.txt and save the copy as config/settings.txt.
   1. Add your User ID. On the Apps and Keys page, under My Account Information, copy the User ID GUID and save it in settings.txt as your IMPERSONATION_USER_GUID.
   2. 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 settings.txt as your INTEGRATION_KEY_JWT.
   3. 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 config/private.key.
   4. Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:8080/authorization-code/callback. Select SAVE.
   5. Set a name and email address for the signer. In settings.txt, save an email address as SIGNER_EMAIL and a name as SIGNER_NAME.
      Note: Protect your personal information. Please make sure that settings.txt will not be stored in your source code repository.
4. Run the launcher: bash launcher.sh
5. Select an API when prompted.
6. Select JSON Web Token when authenticating your account.
7. Select your desired code example.

Troubleshooting CRLF issue on Unix systems

If you are using a Unix-like operating system (such as Mac or Linux), you may see the following error message when running some examples:

examples/eSignature/eg002SigningViaEmail.sh: line 148: syntax error: unexpected end of file

This is because code files use CRLF as the line ending type, which is incompatible with Unix-like operating systems. To fix this issue, follow the steps below:

1. Install dos2unix.
2. Convert the files to use LF as the line ending type by running dos2unix filename.sh.
   • Example: dos2unix eg002SigningViaEmail.sh
3. Rerun the Bash launcher.

ACG embedded signing project

See DocuSign Quickstart overview on the DocuSign Developer Center for more information on how to run the ACG embedded signing project.

Payments code example

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 settings.txt.

License and additional information

License

This repository uses the MIT License. See LICENSE for details.

Pull Requests

Pull requests are welcomed. Pull requests will only be considered if their content uses the MIT License.