Skip to navigation
eSignature SOAP API 101

Authentication

View as Markdown

This page describes functionality for the older eSignature SOAP API. See the REST API Authentication topic for more information on authentication in the more actively-supported eSignature REST API documentation.

All Docusign API methods require authentication. There are three way to pass member credentials:

  • SOAP Header via WS-Security UsernameToken
  • HTTP Header via a custom field “X-Docusign-Authentication”
  • App Password authentication

Starting on August 16th 2021, Docusign began the end-of-life process for all SOAP API authentication flows other than App Password (for SOAP apps).

The Account Management API only supports the HTTP Header or App Password authentication methods, while all others can support either method.

Additionally, the eSignature SOAP API has two API end points: API.asmx and DSAPI.asmx. The API.asmx end point requires the WS-Security UsernameToken in the SOAP header authentication. The DSAPI.asmx and AccountManagement.asmx end points require the HTTP Header or App Password authentication method.

HTTP header authentication

For the HTTP header, access to the API must be enabled for the member login that is being used. This is controlled by combinations of user name, password and integration key. The valid authentication combinations are:

  • User Name, password, integration key Note: this is the preferred option since is provides the highest level of protection. Where the User Name is the API User Name retrieved from the Credential Login() function, the password is the encrypted password retrieved from the AccountManagement GetEncryptedPassword() function, and the integration key is the key provided by Docusign.
  • User Name, password, integration key Where the User Name is the API User Name retrieved from the Credential Login() function, the password is in clear text, and the integration key is the key provided by Docusign.
  • User Name, password, integration key Where the User Name is the user’s email login, the password is in clear text, and the integration key is the key provided by Docusign.

Note that when using the HTTP Header form of authentication, the header variable name is: X-Docusign-Authentication.

One way to provide the HTTP authentication header is to create a subclass from the Web Service and override the GetWebRequest method, as shown in the following example.

Example HTTP header
namespace DSAPI {
  // override of web service interface is required to insert the HTTP header authentication.
  public class DocuSignAcctMgmtService: DSAPI_AcctMgmtWebService.AccountManagementService {
    private string myDSUserId = "";
    private string myDSPassword = "";
    private string myDSIntegrationKey = "";
    public string UserName {
      get {
        return myDSUserId;
      }
      set {
        myDSUserId = value;
     }
    }
    public string Password {
      get {
        return myDSPassword;
      }
      set {
        myDSPassword = value;
      }
    }
    public string IntegrationKey {
      get {
        return myDSIntegrationKey;
      }
      set {
        myDSIntegrationKey = value;
      }
    }
    protected override System.Net.WebRequest GetWebRequest(Uri uri) {
      System.Net.HttpWebRequest r = base.GetWebRequest(uri) as System.Net.HttpWebRequest;
      r.Headers.Add("X-DocuSign-Authentication",
        string.Format(" <
          DocuSignCredentials >
          <
          Username > YOUR USER EMAIL OR ID GOES HERE < /Username> <
          Password > YOUR USER PASSWORD GOES HERE < /Password> <
          IntegratorKey > YOUR INTEGRATION KEY GOES HERE < /IntegratorKey> < /
          DocuSignCredentials >
          ",
          UserName,
          Password,
          IntegrationKey));
      return r;
    }
  }
}

SOAP header authentication

For the WS-Security UsernameToken, the values for the UsernameToken elements can be the same as those used for the HTTP header values.

<wsse:Security soap:mustUnderstand="1">
    <wsu:Timestamp wsu:Id="Timestamp-0741d0e0-529f-49bc-bf86-653238d2532b">
        <wsu:Created>(wsu:Created)2006-01-02T21:26:04Z</wsu:Created>
        <wsu:Expires>(wsu:Expires)2006-01-02T21:31:04Z</wsu:Expires>
    </wsu:Timestamp>
    <wsse:UsernameToken
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="SecurityToken-8d4e766e-a8a2-4bb3-a327-89c34bc7f85f">
        <wsse:Username>(wsse:Username)caa26663-927b-4800-bfdf-d115d1c72f20</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
        <wsse:Nonce>(wsse:Nonce)RumCR4p6U4a7hiX9lUlGWA==</wsse:Nonce>
        <wsu:Created>(wsu:Created)2006-01-02T21:26:04Z</wsu:Created>
    </wsse:UsernameToken>
</wsse:Security>