Skip to navigation
eSignature SOAP API 101Authentication

Using encrypted passwords in SOAP

View as Markdown

This section provides information on requesting and using a Docusign encrypted password in the SOAP api.asmx API where the wsse security header is used for authentication.

Step 1. Find user account

To start the process, use the Credential Login API to find the accounts associated with the user’s credentials. This initial call uses the email address and clear text password.

The response shows that this user has access to two accounts and the BaseUrl shows that one account is on “test” while the second account is on “test2”. In future API calls, you will select the server and endpoint as appropriate for the account you will use. For the example we will use:

Account = https://test.docusign.net/api/3.0
UserId = 47c97f72-xxxx-xxxx-xxxx-75ac3b630bfa

Note: The email address can be used instead of the UserId in API calls.

POST https://test.docusign.net/api/3.0/credential.asmx HTTP/1.1
Host: test.docusign.net
Content-Type: text/xml; charset=utf-8
Content-Length: 458
SOAPAction: "http://www.docusign.net/API/Credential/Login"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Login xmlns="http://www.docusign.net/API/Credential">
      <Email>r.tester@gmail.com</Email>
      <Password>passWordabC2</Password>
      <ReturnBaseUrl>true</ReturnBaseUrl>
    </Login>
  </soap:Body>
</soap:Envelope>

Step 2. Request encrypted password

Next, request the encrypted Password for the user by making a GetEncryptedPassword request to the server where this user’s account is located and providing the credentials in the X-Docusign-Authentication header.

The response returns the encrypted version of the password, such as SBXBCN…9LZuk= .

At this point, if client application (securely) stores the BaseUrl, UserId and encrypted password, then the application does not need to repeat the previous calls unless authentication fails on successive calls.

POST https://test.docusign.net/api/3.0/accountmanagement.asmx HTTP/1.1
Host: test.docusign.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.docusign.net/API/AccountManagement/GetEncryptedPassword"
X-DocuSign-Authentication: <DocuSignCredentials><Username>r.tester@gmail.com</Username><Password>passWordabC2</Password><IntegratorKey>DOCU-KEY-ABC2</IntegratorKey></DocuSignCredentials>
Content-Length: 342
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetEncryptedPassword xmlns="http://www.docusign.net/API/AccountManagement" />
  </soap:Body>
</soap:Envelope>

Step 3. Authenticate request status call

The following request shows how the encrypted password is used, along with the Integrator Key and UserId, to authenticate a Request Status call for an envelope. This same pattern would be used in all successive API calls.

In this case the Integrator Key is [DOCU-KEY-ABC2].

Example request
POST https://test.docusign.net/api/3.0/api.asmx HTTP/1.1
Host: test.docusign.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.docusign.net/API/3.0/RequestStatus"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <soap:Header>
    <wsa:Action>http://www.docusign.net/API/3.0/RequestStatus</wsa:Action>
    <wsa:MessageID>urn:uuid:be6a8f4a-xxxx-xxxx-xxxx-496f207c5c27</wsa:MessageID>
    <wsa:ReplyTo>
  <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>https://test.docusign.net/API/3.0/api.asmx</wsa:To>
    <wsse:Security soap:mustUnderstand="1">
      <wsu:Timestamp wsu:Id="Timestamp-8af36607-xxxx-xxxx-xxxx-e849cd186c93">
        <wsu:Created>2013-10-11T13:34:18Z</wsu:Created>
        <wsu:Expires>2013-10-11T13:39:18Z</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-289a0ed4-xxxx-xxxx-xxxx-f64c692384ae">
        <wsse:Username>[DOCU-KEY-ABC2]47c97f72-xxxx-xxxx-xxxx-75ac3b630bfa</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">SBXBCNHn29VRB8e8cxsMes9LZuk=</wsse:Password>
        <wsse:Nonce>STapZaoS6MuKXmdh2TU1Qw==</wsse:Nonce>
        <wsu:Created>2013-10-11T13:34:18Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <RequestStatus xmlns="http://www.docusign.net/API/3.0">
      <EnvelopeID>D65860E3-xxxx-xxxx-xxxx-4F37ABDED5AA</EnvelopeID>
    </RequestStatus>
  </soap:Body>
</soap:Envelope>