Skip to navigation
TSP API 101

Authentication

View as Markdown

Before your application can make calls to the TSP API, it must authenticate and obtain an access token. This access token proves your app’s identity and authorization. You must submit it with each request to the TSP API. If you’re delegating the creation of the CMS to Docusign, you must provide the same access token you submitted to get the signing information.

TSP authentication uses an extension of the Docusign OAuth framework. This framework requires that you register your TSP as an OAuth client with Docusign.

Prerequisites

Before you can use the TSP API, you need the following:

  1. A Docusign eSignature developer account.

  2. An integration key that identifies your application.

  3. A redirect URI associated with your integration key. The redirect URI points to a web application managed by the TSP. All signers must log in to this page to authenticate and proceed with the signature process. TSPs can use a localhost address during the development phase then an HTTPS once the integration is live.

Once TSPs get their integration key and redirect URI, they can request the Docusign account server for an access token they will use to authenticate in every call to the TSP API.

Authentication in the signature process

Once a TSP registers as an OAuth client with Docusign, it authenticates in the signature process as follows:

  1. In a Docusign document, a signer selects SIGN and CONTINUE to request signatures from the TSP (see Getting Started for more information on this step).

The Docusign account server sends the following information to the TSP:

  • the redirect URI of the TSP (see also Prerequisites above)
  • a standard OAuth authorization code:
HTTP/1.1 302 Found
        Location: https://client.example.org/cb?
        code=SplxlOBeZQQYbYS6WxSbIA

Code sample 1: authentication information sent to the TSP

Note: the OAuth authorization code expires after 2 minutes.

  1. The TSP uses the OAuth authorization code from step 2 to request the creation of a token to access DocuSIgn (see also Access token request below).
  2. Docusign returns an access token to the TSP.
  3. The TSP can now use the access token to call the next TSP API endpoint in the signing flow (see also Geting Started. This token is only valid for this transaction. All subsequent requests require a new access token.

Access token request

The POST /oauth/token endpoint contains all the claims needed to complete every request authentication step.

POST oauth/token HTTP/1.1
Host: account-d.docusign.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0
grant_type=authorization_code
    &code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

The Authorization header follows the OAuth 2.0 Basic authentication schema described in Section 2.3.1 of the OAuth 2.0 RFC. It concatenates the client ID, a semicolon, and the client secret. Docusign provides the client ID and client secret when TSPs configure their applications.

In the above example, the value of the client ID is “clientId” and the value of the client secret is “clientSecret”. Optionally, you can pass this information as the client_id and client_secret POST parameters.

Access token response

The response to the access token request contains the following parameters:

  • access_token: The access token used by the TSP to authenticate with the Docusign APIs.
  • expires_in: The lifetime of the access token.
  • token_type: The Bearer, describing the usage of the access token.
  • user_api: The base URI used for subsequent requests to the TSP REST APIs.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache{
"access_token": "(access token example removed for document brevity)",
"expires_in": 28800,
"token_type": "Bearer",
"user_api": "https://{server}.docusign.net"
}

TSPs must use the returned token in all subsequent requests to authenticate to Docusign. They must also ensure they use the returned base URI in their calls to the TSP API. Note that if you’re calling the CMS API, you must use the dedicated base URL.