ServiceNow provides a DocuSign eSignature Spoke via IntegrationHub, which allows users to automate document signing workflows using Flow Designer and other low-code tools. This spoke supports sending documents for signature, managing envelopes, and syncing templates directly within ServiceNow.
However, if you are not using the spoke, whether due to licensing constraints, customisation requirements, or preference for direct API integration, this guide walks through the manual integration of DocuSign with ServiceNow using OAuth 2.0 and JWT authentication.
It is designed for developers and system administrators who want to enable secure digital signing workflows within ServiceNow without relying on the prebuilt spoke.
Note: This implementation was completed using the Washington release of ServiceNow and remains applicable as of the Yokohama release. The steps and configurations described here continue to work reliably in current environments.
Disclaimer: All keys, credentials, and configuration values shown in this guide are sample data only. Do not use them in your configuration. Always generate your own secure credentials and follow your organisation’s security policies.
Step 1: Set Up Your DocuSign Developer Account and Integration App
Before integrating DocuSign with ServiceNow, you need to set up a DocuSign Developer Account. This account gives you access to the sandbox environment where you can test API calls, authentication flows, and envelope creation without affecting live data.
Once your integration is working in development, you can promote your keys to production using this guide from DocuSign.
Create an Integration App
This app acts as the bridge between ServiceNow and DocuSign. It provides the credentials needed for authentication and API access.
| Step | Action |
|---|---|
| 1 | Navigate to Settings > Apps and Keys in your DocuSign Developer Account |
| 2 | Click Add App and Integration Key |
| 3 | Save the credentials you obtain. These are required for OAuth and JWT setup |
The keys below are for illustration only. They show the format and type of credentials you’ll need to copy from your own DocuSign integration app.
| Credential Type | Sample Value | Purpose |
|---|---|---|
| Integration Key | d2a87889-d1fb-4670-bf13-81dcfbebfe8b | Identifies your app when making API requests |
| Secret Key | aae0827b-a407-4a99-9467-6fde72aa77b9 | Authenticates your app securely during token exchange |
These credentials are required for both OAuth 2.0 and JWT authentication flows. Keep them secure and never expose them in client-side code or public repositories.
Generate RSA Keypair
After creating your DocuSign Integration App, you need to generate an RSA keypair. This keypair is used to digitally sign JWT tokens, which ServiceNow will use to authenticate securely with DocuSign without requiring user interaction.
This step is essential for enabling JWT Bearer Grant authentication, which is ideal for server-to-server integrations.
| Step | Action |
|---|---|
| 1 | Click Generate RSA Keypair in your DocuSign Integration App settings |
| 2 | Copy the following values: |
– RSA Keypair ID: 3cd29b51-c6ba-4b93-b85e-b1f94bd24f06 (sample only) | |
| – Public Key and Private Key (used later to sign JWT tokens) |
The keys shown above are for illustration only. They show the format and type of values you’ll need to copy from your own DocuSign setup. Keep your private key secure and never expose it publicly.
Configure Redirect URIs
Redirect URIs are a required part of the OAuth 2.0 Authorization Code Grant flow. They tell DocuSign where to send the authorization code after a user successfully grants access. This URI must match exactly between your DocuSign Integration App and your ServiceNow instance configuration.
| Field | Value / Example | Purpose / Description |
|---|---|---|
| Redirect URI | https://yourinstancename.service-now.com/oauth_redirect.do | Replace yourinstancename with your actual ServiceNow instance name. This is where DocuSign will redirect the user after authorisation. |
This URI must be registered in your DocuSign Integration App settings. If it doesn’t match exactly, the OAuth flow will fail and ServiceNow won’t be able to retrieve the access token.
Configure Authentication Method and Allowed HTTP Methods
These settings define how your DocuSign Integration App will authenticate and what types of HTTP requests it can accept. This is essential for enabling secure communication between ServiceNow and DocuSign.
Authentication Method
| Setting | Value | Purpose / Description |
|---|---|---|
| Secure Client Secret Storage | Yes | Confirms that your application (ServiceNow) can securely store the client secret |
| Authentication Method | Authorization Code Grant | Enables OAuth 2.0 Authorization Code flow, which is used for user-authorised access |
This ensures that DocuSign will issue tokens using the Authorization Code Grant flow, which is compatible with ServiceNow’s OAuth setup.
Allowed HTTP Methods
| Method | Purpose / Description |
|---|---|
GET | Used for retrieving data, such as checking connection or fetching envelope status |
POST | Used for sending data, such as creating envelopes or submitting documents |
| (Others) | You may enable additional methods depending on your use case (e.g., PUT, DELETE) |
These methods define what types of API calls your integration app can handle. For most ServiceNow-to-DocuSign interactions,
GETandPOSTare sufficient.
You may refer to this ServiceNow KB article, but not all steps are required if you’re not using ServiceNow Spokes.
Step 2: Generate the JKS File for JWT Authentication
To enable JWT authentication in ServiceNow, you need to create a Java Key Store (JKS) file that contains your DocuSign private key. This file allows ServiceNow to securely sign JWT tokens when authenticating with DocuSign.
JWT authentication is ideal for server-to-server integrations where user interaction is not required. It allows ServiceNow to impersonate a DocuSign user and perform actions like sending envelopes or retrieving status updates.
Tools Required
| Tool | Purpose | Download / Source |
|---|---|---|
| OpenSSL for Windows | Used to generate a certificate and export it to PKCS12 format | Download here OpenSSL Wiki |
| Java JDK | Required to run the keytool command, which converts PKCS12 to JKS format | Download here |
You’ll use OpenSSL to generate a certificate from your private key, then convert it to a JKS file using Java’s keytool utility. This JKS file will later be uploaded to ServiceNow as part of the JWT configuration.
Steps to Generate the JKS File for JWT Authentication
This process converts your DocuSign private key into a Java Key Store (JKS) file, which ServiceNow uses to sign JWT tokens securely. The JKS file is a required component for enabling JWT Bearer Grant authentication.
Step-by-Step Instructions
| Step | Action | Purpose / Description |
|---|---|---|
| 1 | Create a private key file Copy the private key from your DocuSign Integration App and save it as privatekey.key. Move this file to C:\certificate. | This file will be used to generate a certificate for signing JWT tokens. |
| 2 | Generate a certificate using OpenSSL Open Command Prompt as Administrator and run: cd "C:\Program Files\OpenSSL-Win64\bin"openssl req -new -x509 -key C:\certificate\privatekey.key -out cacert.pem -days 1095 | This creates a self-signed certificate (cacert.pem) from your private key. |
| 3 | Enter certificate details when prompted Examples: Country, State, Organization, Email | These details are embedded in the certificate and help identify the source of the key. |
| 4 | Export to PKCS12 format Run: openssl pkcs12 -export -in cacert.pem -inkey C:\certificate\privatekey.key -certfile cacert.pem -out testkeystore.p12 | Converts the certificate and key into a .p12 file. You’ll be prompted to create a secure export password. Store it safely. |
| 5 | Convert to JKS format using Java keytool Change directory: cd "C:\Program Files\Java\jdk-22\bin"Then run: keytool -importkeystore -srckeystore "C:\Program Files\OpenSSL-Win64\bin\testkeystore.p12" -srcstoretype pkcs12 -destkeystore ranDocusign.jks -deststoretype JKS | Converts the .p12 file into a .jks file. You’ll be prompted for the password you created in the previous step. |
| 6 | Locate the JKS file The file ranDocusign.jks will be created in your Java bin directory.:C:\Program Files\Java\jdk-22\bin> | This file will be uploaded to ServiceNow in the next step to configure JWT authentication. |
The JKS file securely stores your private key and certificate. It is essential for ServiceNow to sign JWT tokens and authenticate with DocuSign without user interaction.
Step 3: Configure ServiceNow for OAuth and JWT
Create Certificate in ServiceNow
The certificate in ServiceNow stores your DocuSign private key securely in a Java Key Store (JKS) format. This is required for signing JWT tokens during authentication. Without this certificate, ServiceNow cannot generate valid JWTs to communicate with DocuSign.
| Step | Field / Action | Details |
|---|---|---|
| 1 | Navigation | Go to System Definition > Certificates |
| 2 | Create Certificate | Click New |
| 3 | Name | DocuSign Certificate – This is a label for your keystore. |
| 4 | Type | Java Key Store – Select this to match the format of the .jks file you generated. |
| 5 | Password | Enter the password used when converting the PKCS12 file to JKS using the keytool command. |
| This password unlocks the keystore and allows ServiceNow to access the private key for JWT signing. | ||
| Important: Store this password securely. | ||
| 6 | Upload File | Upload the .jks file you generated earlier. |
| 7 | Troubleshooting | If ServiceNow does not allow the upload, proceed to the next troubleshooting step (not specified). |
This certificate is a critical part of the JWT authentication flow. It ensures that ServiceNow can securely sign tokens using your DocuSign private key.
Create JWT Key in ServiceNow
JWT (JSON Web Token) authentication allows ServiceNow to securely communicate with DocuSign without requiring user interaction each time. The JWT Key configuration tells ServiceNow how to sign tokens using the certificate you uploaded earlier.
| Step | Field / Action | Details |
|---|---|---|
| 1 | Navigation | Go to System OAuth > JWT Keys |
| 2 | Create JWT Key | Click New |
| 3 | Name | DocuSign JWT Keys – This is a label for your JWT key configuration. |
| 4 | Signing Keystore | Select the certificate you created earlier (e.g., DocuSign Certificate) |
| 5 | Signing Algorithm | RSA 256 – This is the algorithm used for signing JWTs. |
| 6 | Signing Key | Enter the password used when creating the JKS file via the keytool command. |
| This password allows ServiceNow to access the private key stored in the keystore. | ||
| Important: Store this password securely. It is required for JWT token signing with DocuSign. |
Create JWT Provider in ServiceNow
The JWT Provider in ServiceNow defines how the platform will generate and manage JWT tokens when authenticating with DocuSign. It links the signing configuration (your JWT Key) with the logic that builds the token and sets its expiration.
To configure it:
| Step | Field / Action | Details |
|---|---|---|
| 1 | Navigation | Go to System OAuth > JWT Providers |
| 2 | Create JWT Provider | Click New |
| 3 | Name | DocuSign JWT Provider – This is a label for your configuration. |
| 4 | Signing Configuration | Select the JWT Key you created earlier (e.g., DocuSign JWT Keys) |
| This tells ServiceNow which keystore and algorithm to use for signing the token. | ||
| 5 | JWT API Script | JWTTokenInternal – This is the default script used to generate the JWT payload. |
| 6 | Expiry Interval | 60 seconds – Defines how long the token is valid before it expires. |
| A short interval like 60 seconds is typical for secure, short-lived tokens. | ||
| 7 | Security Note | Important: The JWT Provider enables ServiceNow to authenticate with DocuSign using JWT Bearer Grant. It ensures tokens are signed correctly and securely using your private key. |
Add Standard Claims
These claims are required for JWT authentication:
| Claim | Description | Sample Value |
|---|---|---|
aud | Audience – the intended recipient of the token. For DocuSign, this is usually the base URL of the API you’re calling. | account-d.docusign.com |
iss | Issuer – the Integration Key from your DocuSign app. This identifies the application making the request. | d2a87889-d1fb-4670-bf13-81dcfbebfe8b |
sub | Subject – the user ID (GUID) of the DocuSign user on whose behalf the request is made. This user must have admin privileges. | cfd62061-463a-41b7-b58a-859cbb026ae6 |
scope | Permissions requested. For signing documents, use signature impersonation. | signature impersonation |
For more details, refer to:
Step 4: Create OAuth Profile in ServiceNow
The OAuth Profile defines how ServiceNow connects to DocuSign using the Authorization Code Grant method. This setup allows ServiceNow to securely obtain access and refresh tokens after a user authorises the connection. It is essential for enabling authenticated API calls to DocuSign.
| Field | Value / Example | Purpose / Description |
|---|---|---|
| Name | DocuSign OAuth | A label for your OAuth configuration |
| Client ID | d2a87889-d1fb-4670-bf13-81dcfbebfe8b (sample only) | The Integration Key from your DocuSign app. Identifies the application making the request |
| Client Secret | aae0827b-a407-4a99-9467-6fde72aa77b9 (sample only) | The Secret Key from your DocuSign app. Used to authenticate the app securely |
| OAuth API Script | OAuthUtil | The default script used to handle OAuth token exchange |
| Default Grant Type | Authorization Code | Enables user-based authorisation flow |
| Accessible From | All application scopes | Makes the profile usable across your ServiceNow instance |
| Authorization URL | https://account-d.docusign.com/oauth/auth | Where users are redirected to authorise access |
| Token URL | https://account-d.docusign.com/oauth/token | Where ServiceNow exchanges the authorisation code for an access token |
| Redirect URL | https://{instance}.service-now.com/oauth_redirect.do | Replace {instance} with your actual ServiceNow instance name. DocuSign sends the authorization code here after user consent |
This profile is required for ServiceNow to initiate and manage OAuth 2.0 connections with DocuSign using the Authorization Code Grant flow.
Add Entity Profiles
Entity Profiles in ServiceNow define how each OAuth or JWT credential will be used. They act as a bridge between your OAuth Profile and the actual credentials used in IntegrationHub or REST API calls. You can have multiple profiles for different grant types (e.g., Authorization Code vs JWT Bearer), and specify which one is the default.
| Name | Grant Type | Is Default | Purpose / Description |
|---|---|---|---|
DocuSign OAuth Profile | Authorization Code | True | Used for user-authorised access. This profile is the default for flows requiring user consent |
DocuSign JWT Profile | JWT Bearer | False | Used for server-to-server authentication without user interaction. Ideal for background automation |
These profiles allow ServiceNow to choose the correct authentication method when making API calls to DocuSign, depending on the use case.
Step 5: Create Credentials in IntegrationHub
Credentials in IntegrationHub allow ServiceNow to authenticate securely when making REST API calls to DocuSign. You need to create two credentials: one for OAuth (Authorization Code Grant) and one for JWT (JWT Bearer Grant). These credentials reference the entity profiles you configured earlier and are used by Flow Designer, Scripted REST APIs, or custom integrations.
OAuth Credential
| Field | Value / Example | Purpose / Description |
|---|---|---|
| Name | DocuSign OAuth Credential | A label for the credential |
| OAuth Entity Profile | DocuSign OAuth Profile | Links to the entity profile using Authorization Code Grant |
| Applies To | All MID servers | Ensures the credential is available across all integration points |
| Order | 100 | Determines priority if multiple credentials exist |
After saving, click Get OAuth Token to verify the setup. If successful, ServiceNow will retrieve a valid access and refresh token from DocuSign.
JWT Credential
Repeat previous stem, click Create New, select OAuth 2.0 and enter the following information:
| Field | Value / Example | Purpose / Description |
|---|---|---|
| Name | DocuSign JWT Credential | A label for the credential |
| OAuth Entity Profile | DocuSign JWT Profile | Links to the entity profile using JWT Bearer Grant |
| Applies To | All MID servers | Ensures the credential is available across all integration points |
| Order | 100 | Determines priority if multiple credentials exist |
After saving, click Get OAuth Token to verify the JWT setup. If successful, ServiceNow will generate a signed JWT, exchange it for an access token, and confirm the connection to DocuSign.
These credentials are essential for enabling secure, token-based communication between ServiceNow and DocuSign. They allow your flows and scripts to authenticate without hardcoding sensitive information.
Step 6: Test the Integration
Once your OAuth and JWT credentials are configured, it’s important to verify that ServiceNow can successfully connect to DocuSign and perform key operations. This test script does two things:
- Confirms connectivity by calling the DocuSign login endpoint.
- Creates and sends an envelope using a sample PDF attachment stored in ServiceNow.
This helps ensure that your authentication setup and REST message configurations are working correctly.
Use the following script to test login and envelope creation. This script verifies that your DocuSign integration is functional. If the connection and envelope creation succeed, your setup is complete and ready for use in production workflows.
// Test connection to DocuSign
var r = new sn_ws.RESTMessageV2('global.DocuSign_Login', 'Default GET');
var response = r.execute();
gs.info("connectToDocuSign: " + response.getStatusCode());
// Prepare document from sys_attachment
var gr = new GlideRecord('sys_attachment');
gr.get('fad537d73387c6108c66e6b45d5c7b83'); // Replace with your actual sys_id
var sa = new GlideSysAttachment();
var binData = sa.getBytes(gr);
var encData = GlideStringUtil.base64Encode(binData);
// Create envelope and send for signature
var createEnvelope = new sn_ws.RESTMessageV2('global.DocuSign_Create_Envelope', 'Default POST');
var jsonBody = {
emailSubject: "Please sign the document",
documents: [{
name: "sample.pdf",
documentId: "1",
documentBase64: encData
}],
recipients: {
signers: [{
deliveryMethod: "Email",
name: "Arlene H1",
email: "myemail1@example.com",
routingOrder: "1",
recipientId: "1"
}],
carbonCopies: [{
email: "myemail2@example.com",
name: "Arlene H2",
routingOrder: "2",
recipientId: "2"
}]
},
status: "sent",
messageLock: "true"
};
createEnvelope.setRequestBody(JSON.stringify(jsonBody));
var createEnvelopeResponse = createEnvelope.execute();
gs.info("createEnvelopeResponse: " + createEnvelopeResponse.getStatusCode());
gs.info("createEnvelopeResponseBody: " + createEnvelopeResponse.getBody());
Final Thoughts
This integration enables secure, automated document signing workflows directly within ServiceNow. By using both OAuth and JWT, you can support impersonated signing, delegated access, and other advanced use cases.
Reminder: Replace all sample keys, secrets, and user IDs with your own secure credentials.
Leave a Reply