Authenticating With DocuSign's API


Your signed documents, or the ones waiting for electronic signature, can represent your livelihood. You don't want just anyone, or a bot, accessing your DocuSign account. You want to ensure that your application, and only your application, communicates with DocuSign's repository to get, sign, and save your documents. A secure and reliable authentication method is necessary.

DocuSign uses the credentials of a member account authorized to access the DocuSign API. There are three elements to the credentials:

  • User Name: the email address of the member who is authorized to use the DocuSign API. Optionally, a GUID that is provided by DocuSign to represent the email address can be used instead.
  • Password: the password of the member.
  • Integrators Key: a GUID that represents the application. This key can be activated while working in the DevCenter sandbox provided for development, and travels with the application when it is successfully promoted to production by DocuSign's certification process.

All three of these elements are required for authentication of a solution in the production environment.

Our API is flexible enough to adapt to any integration use case required of it. In keeping with this philosophy, we provide different ways to use these three elements to authenticate a Web Service API method. The table below summarizes them:

Authentication in the SOAP header uses a WS-Security Username Token. All web languages that provide a SOAP Client library supports it, and historically it has been the standard for authenticating SOAP Web Service calls.

Authentication in the HTTP Header uses a small XML string that packages the credentials. For some languages, implementing authentication this way is easier than implementing authentication through a WS-Security method. An example of how to do this in C#.NET for the AccountManagement API:
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 myDSIntegratorKey = "";

public string UserName
get { return myDSUserId; }
set { myDSUserId = value; }

public string Password
get { return myDSPassword; }
set { myDSPassword = value; }

public string IntegratorKey
get { return myDSIntegratorKey; }
set { myDSIntegratorKey = value; }
protected override System.Net.WebRequest GetWebRequest(Uri uri)

System.Net.HttpWebRequest r = base.GetWebRequest(uri) as System.Net.HttpWebRequest;

return r;
This code can be found in our online documentation in the DocuSign API Guide .

Internal authentication happens in the body of the SOAP call rather than any of the headers and is limited to our Credentials API. An example of how to do this in PHP (5.3.x) from within a wsdl2php generated proxy class that overrides the _doRequest function for the PHP SoapClient class:
private $_username;
private $_password;

public function setCredentials($username, $password)
$this->_username = $username;
$this->_password = $password;
public $_lastRequest;
function __doRequest($request, $location, $saction, $version, $one_way = null)
include_once 'WSSESoap.php';
include_once 'WSASoap.php';

$dom = new DOMDocument('1.0');
$objWSA = new WSASoap($dom);
$dom = $objWSA->getDoc();
$objWSSE = new WSSESoap($dom);
if (isset($this->_username) && isset($this->_password)) {
$objWSSE->addUserToken($this->_username, $this->_password);
/* Sign all headers to include signing the WS-Addressing headers */
$objWSSE->signAllHeaders = TRUE;
// if you need to do binary certificate signing you can uncomment this (and provide the path to the cert)
/* create new XMLSec Key using RSA SHA-1 and type is private key */
// $objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA1, array('type'=>'private'));

/* load the private key from file - last arg is bool if key in file (TRUE) or is string (FALSE) */

/* Sign the message - also signs appropraite WS-Security items */
// $objWSSE->signSoapDoc($objKey);

/* Add certificate (BinarySecurityToken) to the message and attach pointer to Signature */
// $token = $objWSSE->addBinaryToken(file_get_contents(CERT_FILE));
// $objWSSE->attachTokentoSig($token);
$request = $objWSSE->saveXML();
$this->_lastRequest = $request;

return parent::__doRequest($request, $location, $saction, $version);
This code sample can be found in the DocuSign electronic signature SDK . So sign up for a free DevCenter account to get your very own credentials and try out the DocuSign API!