Using Legacy Header Authentication

Legacy Header Authentication is the earliest authentication protocol in the DocuSign platform. You may see it used in many examples.

Legacy Header authentication was formerly recommended for service integrations. DocuSign recommends new service integrations be built with Service Integration Authentication.

Legacy header authentication does not work for accounts that require single sign-on (SSO) or two-factor authentication.

With Legacy Header Authentication you provide your account credentials in every request in an X-DocuSign-Authentication header.

You can provide your credentials as a JSON object or as an XML object. In both cases the object contains

  • The email address of your developer account.
  • The account’s password.
  • Your integrator key.

The JSON object looks like this:

{
  "Username":"developer@example.com",
  "Password":"S3cre+p455w0Rd",
  "IntegratorKey":"your integrator key"
}

In JSON strings, the backslash \ is interpreted as an escape character. If your password contains a backslash, be sure to escape it with another backslash. For example, if your password is Secret\Password, you would need to write it as "Secret\\Password" in the JSON object. See the JSON website for more information.

The XML object looks like this:

<DocuSignCredentials>
 <Username>developer@example.com</Username>
 <Password>S3cre+p455w0Rd</Password>
 <IntegratorKey>your integrator key</IntegratorKey>
</DocuSignCredentials>'

Get Your Base URL

Your first call to the DocuSign REST API is to the login_information endpoint to obtain the user’s account and baseUrl information. You’ll use the baseURL to make more requests.

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username":"developer@example.com",
                "Password":"S3cre+p455w0Rd",
                "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad" }'\
          https://demo.docusign.net/restapi/v2/login_information
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 366
Content-Type: application/json; charset=utf-8
Date: Thu, 02 Jun 2016 02:36:58 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
  "loginAccounts": [
    {
      "name": "Dev Eloper",
      "accountId": "1703061",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/1703061",
      "isDefault": "true",
      "userName": "Dev Eloper",
      "userId": "1470ff66-f92e-4e8e-ab81-8c46f140da37",
      "email": "developer@example.com",
      "siteDescription": ""
    }
  ]
}

The result contains information about your account. The most useful value to you right now is the baseUrl. This is the URL that you’ll use for all your requests. In the production environment your baseUrl will contain the address of an production server.

Although the endpoint has “login” in its name, it does not actually log you in to the DocuSign platform. (The API is sessionless.) Rather, it provides information about the user’s accounts and their baseUrls for use in subsequent requests.

As a side-effect of making the API request, if your authentication header does not include valid information, (such as an incorrect password), the call will be rejected.