Data import

Connection details and authentication

The DocuSign connector supports the following OAuth 2.0 authentication approaches:

• Refresh token with OAuth2 Custom
• JWT bearer grant with OAuth2 JWT

Use the same DocuSign environment for authorization, token requests, and API requests.

Environment	Authorization server	API base URI
Developer	https://account-d.docusign.com	Returned by the DocuSign UserInfo endpoint, typically https://demo.docusign.net.
Production	https://account.docusign.com	Returned by the DocuSign UserInfo endpoint.

warning

Do not store access tokens, refresh tokens, client secrets, private keys, or authorization codes directly in documentation or non-secure configuration fields. Use secure placeholders for sensitive values.

Find the DocuSign account ID and API base URI

After obtaining an access token, call the DocuSign UserInfo endpoint.

Developer environment:

GET https://account-d.docusign.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

Production environment:

GET https://account.docusign.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

The response contains an accounts array. Use the required account entry's account_id and base_uri values.

Example:

{
  "accounts": [
    {
      "account_id": "00000000-0000-0000-0000-000000000000",
      "account_name": "Example account",
      "base_uri": "https://demo.docusign.net",
      "is_default": true
    }
  ]
}

Construct the connector Base URL as follows:

{base_uri}/restapi/v2.1/accounts/{account_id}/

Example:

https://demo.docusign.net/restapi/v2.1/accounts/00000000-0000-0000-0000-000000000000/

Refresh token

Use this approach when the connector must authenticate through a DocuSign authorization-code grant and renew access tokens with a refresh token.

Prerequisites

Before configuring the connection, obtain the following information from the DocuSign application configuration:

• Integration Key, also called the Client ID
• Client secret
• Registered redirect URI
• DocuSign user who can consent to the application
• DocuSign account ID and API base URI

The user granting consent must have access to the DocuSign account that the connector imports.

Obtain an authorization code

Open the authorization URL in a browser and sign in as the DocuSign integration user.

Developer environment:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20extended&client_id={client_id}&redirect_uri={url_encoded_redirect_uri}

Production environment:

https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20extended&client_id={client_id}&redirect_uri={url_encoded_redirect_uri}

The redirect_uri value must exactly match a redirect URI registered for the DocuSign application.

The extended scope allows the integration to receive refresh tokens suitable for a long-running connection. The authorization URL may also include a URL-encoded login_hint parameter.

After consent, DocuSign redirects the browser to the registered redirect URI and appends a temporary authorization code:

https://example.com/callback?code={authorization_code}

warning

The authorization code is short-lived and single-use. Change it immediately and do not reuse or store it as the refresh token.

Exchange the authorization code for tokens

Send a form-encoded POST request to the token endpoint. Authenticate the application with HTTP Basic authentication, where the username is the Integration Key and the password is the client secret.

Developer environment:

POST https://account-d.docusign.com/oauth/token
Authorization: Basic BASE64({client_id}:{client_secret})
Content-Type: application/x-www-form-urlencoded

 grant_type=authorization_code&code={authorization_code}

Production environment:

POST https://account.docusign.com/oauth/token
Authorization: Basic BASE64({client_id}:{client_secret})
Content-Type: application/x-www-form-urlencoded

 grant_type=authorization_code&code={authorization_code}

A successful response contains an access token and refresh token:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 28800
}

Store the returned refresh_token as a secure value. Do not enter the authorization code or access token in the refresh-token placeholder.

Configure the Omada connection

Parameter	Value
Base URL	{base_uri}/restapi/v2.1/accounts/{account_id}/
Authentication type	OAuth2 Custom
Token endpoint	Developer: https://account-d.docusign.com/oauth/token Production: https://account.docusign.com/oauth/token
OAuth token type	Bearer
OAuth token expiration time in seconds	27000
Auth request body	grant_type=refresh_token&refresh_token=#SECURE1&client_id=#SECURE2&client_secret=#SECURE3
Placeholder values	See the secure placeholder example below
Auth request content type	application/x-www-form-urlencoded
Authentication server response format	JSON
Access Token Location	access_token
Authorization header	Authorization
Headers	Optional. See the request headers example below
Test connection	Select the checkbox
Test query	users

Secure placeholder example:

#SECURE1={refresh_token}
#SECURE2={client_id}
#SECURE3={client_secret}

The connector substitutes the secure placeholder values into the authentication request body before sending the request.

Optional request headers:

{"Request":{"Accept":"application/json"}}

Do not add a static Bearer token to the Headers field. The connector obtains the access token from the authentication response and adds it to API requests using the configured Authorization header and Bearer token type.

Refresh request sent by the connector

The configured connection sends a request equivalent to:

POST https://account-d.docusign.com/oauth/token
Content-Type: application/x-www-form-urlencoded

 grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

For production, use https://account.docusign.com/oauth/token.

DocuSign returns a new access token and may return a replacement refresh token. The connection must continue using the current valid refresh token returned by DocuSign.

Test the refresh-token connection

Use the following test query:

users

With the configured Base URL, the connector sends a request equivalent to:

GET {base_uri}/restapi/v2.1/accounts/{account_id}/users
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

A successful response confirms that:

• The token endpoint is correct for the selected environment.
• The refresh token is valid.
• The account ID belongs to an account available to the consenting user.
• The API base URI is correct for that account.

Refresh-token troubleshooting

Error	Likely cause	Resolution
invalid_grant with expired_client_token	The authorization code expired or was already used.	Generate a new authorization code and exchange it immediately.
invalid_grant during refresh	The refresh token is expired, revoked, incomplete, or belongs to another environment.	Obtain a new authorization code and refresh token in the correct environment.
invalid_client	The Integration Key and client secret do not match, or the secret is no longer active.	Verify the application credentials and create a new secret when required.
HTTP 401 from the API	The access token is invalid for the account, or the user cannot access the account.	Verify the account_id, base_uri, and consenting user.
HTTP 404 from the API	The Base URL or relative query is malformed.	Verify that the Base URL ends with /accounts/{account_id}/ and use users as the test query.

JWT token

Use JWT authentication for a non-interactive service integration where the DocuSign user has granted impersonation consent.

Parameter	Value
Base URL	{base_uri}/restapi/v2.1/accounts/{account_id}/
Authentication type	OAuth2 JWT
Token endpoint	Developer: https://account-d.docusign.com/oauth/token
Production: https://account.docusign.com/oauth/token
OAuth token type	Bearer
JWT Encryption algorithm	RSASSA-PKCS1-v1_5 using SHA-256, RS256
JWT Type	JWT
JWT Public key ID	Enter a non-empty value, for example test
JWT X.509 Certificate Thumbprint	Enter a non-empty value, for example test
JWT Token Parameter	assertion
JWT Issuer	The Integration Key, also called Client ID, from the DocuSign application
JWT Subject	The DocuSign User GUID with impersonation rights
JWT Audience	Developer: account-d.docusign.com
Production: account.docusign.com
JWT Expiration time in seconds	Maximum 3600
JWT Additional claims	scope,signature impersonation
JWT Private key	Private RSA key in PEM format
Test connection	Select the checkbox
Test query	users

The private key must start with:

-----BEGIN RSA PRIVATE KEY-----

note

Although DocuSign does not require the JWT Public key ID or JWT X.509 Certificate Thumbprint, Omada sends these fields by default. Enter a non-empty value such as test to prevent connection errors.

Security recommendations

• Store client secrets, refresh tokens, and private keys only in secure fields.
• Rotate a secret or token immediately if it is exposed.
• Do not copy access tokens into static request headers.
• Keep developer and production credentials separate.
• Use the base_uri returned by the UserInfo endpoint instead of assuming a production data-center hostname.
• Grant only the scopes and DocuSign permissions required by the integration.

Related DocuSign documentation

• Authorization Code Grant
• Using refresh tokens
• UserInfo endpoint

Queries and mappings

Users - Accounts

Parameters:

Tab	Parameter	Value
General	URL	users
Advanced	http verb	GET

Mappings:

Destination	Operator	Source
Business key	Map	userId
Unique ID	Map	userId
Account Name	Map	email
Display Name	Map	userName
Status	Expression	(userStatus == "ActivationSent" || userStatus == "ActivationRequired" || userStatus == "Active") ? "Active" : "Disabled"
Valid from	Map	createdDateTime
Distinguished name	Map	userId

Groups - Resources

Parameters:

Tab	Parameter	Value
General	URL	groups
Advanced	http verb	GET

Mappings:

Destination	Operator	Source
Business key	Map	groupId
Security resource business key	Map	groupId
Name	Map	groupName
Category	Constant	Permission
Type	Constant DocuSign	Group
Short name	Map	groupId

Groups - Assignments

Parameters:

Tab	Parameter	Value
General	URL	groups
Advanced	http verb	GET
Nested Requests	Nested URL	groups/{PARENT_groupId}/users

Mappings:

Destination	Operator	Source
Resource business key	Map	PARENT_groupId
Account – business key	Map	userId
Status	Expression	(userStatus == "activationsent" |\ userStatus == "activationrequired" || userStatus == "active") ? "Active" : "Disabled"

Permission Profiles – Resources

Parameters:

Tab	Parameter	Value
General	URL	permission_profiles
Advanced	http verb	GET

Mappings:

Destination	Operator	Source
Business key	Map	permissionProfileId
Security resource business key	Map	permissionProfileId
Name	Map	permissionProfileName
Category	Constant	Permission
Type	Constant	DocuSign Permission Profile
Short name	Map	permissionProfileId

Permission Profiles - Assignments

Parameters:

Tab	Parameter	Value
General	URL	users
General	Filter	permissionProfileId != "" /
Advanced	http verb	GET

Mappings:

Destination	Operator	Source
Resource business key	Map	permissionProfileId
Account – business key	Map	userId
Status	Expression	(userStatus == "ActivationSent" /

Account rules

Ownership rule

The account owner is set to the identity where the Email value of the identity matches the Name value of the account.

Field	Value
Type	Identity lookup
Join reason	Exact Match
Account attribute	Name
Identity attribute	Email

Classification rule

If an identity with the account attribute Identity join reason Equals Exact Match, the account type is set to Email.

Field	Value
Account type	Personal
Scope attribute	Identity join reason
Scope operator	Equals
Scope value	Exact Match