Docusign: Oauth Flow Outlined
Sign, Sealed, Delivered
In my most recent Ruby/React project I was tasked with getting a digital signature feature working. I researched a bit and found Docusign to be a highly recommended API for accomplishing signatures online. After a week I can honestly say its one of the more challenging API’s I’ve had to deal with. Here is a breakdown of how to get oauth working.
Step 1
The first thing you need to do is sign-up for a Docusign Developer Account. There are actually two types of accounts so make sure you are creating a Developer Account and not a standard one. Now you can create a demo project to get things working. You will need setup a project in order to use their API. Go to Apps and Keys in the settings Tab
And you will see the option create a new App and Keys on the right
Here you can make a new app which will get you an integration key that Docusign will use for confirmation purposes later. There will also be other variables such as the API account ID (Your personal ID number), a redirect url (for our purposes it will be a localhost address), and a secret key (make sure you save this key somewhere you can secure and access later as you will only have one chance to see it.)
One of the most important things to setup is what kind of Authorization to use. There are three different types of Authorization that should be selected based on the specifics of your app. Here is a great explanation on when to use which one from the Docusign Official Docs.
For this example we are going to go with Authorization Code Grant (or ACG).
Once you have the necessary variables assigned you can start your oath flow from your project.
Step 2 auth_code
The first step to actually hitting the API is to retrieve the auth_code. We will be making a GET request to this URL in this format (This flow is contingent on us using the ACG method of Authorization)
NOTE: The base URL will change depending on whether you are setting up for a demo or production environment. Here we are hitting the demo url:
https://account-d.docusign.com/oauth/auth?
response_type=code
&scope=signature
&client_id="YOUR_INTEGRATION_KEY"
&redirect_uri="YOUR_REDIRECT_URI"
Make sure your integration key and redirect_uri match the variables in your app (check your docusign dashboard to confirm). If successful you should get a response object containing an auth_code.
Check the networking tab and see if the response contains the code:
Awesome! Now we need to trade in that auth_code for an access token.
Step 3 access_token
The next step is to make a POST request to Docusign with the obtained auth_code.
Here is an example in the sandbox but lets break it down a bit more. We are going to be posting a curl request to
"https://account-d.docusign.com/oauth/token"there are some header and body values we need to include:
The ‘Content-Type’ must be ‘x-www-form-urlencoded’.
The “Authorization” must start with the “Basic” followed by the Base64 values of your integration and secret key concatenated with a colon.
The body includes our auth_code value we got from our initial fetch in step 2.
We now get a response object containing our access_token!
Step 4 user’s_base_uri
The last step in our oath flow is to make an API call with the access_token we just got and a base URI unique to the user on whose behalf the application is making the API call. We will be a making a GET request to
https://account-d.docusign.com/oauth/userinfothis is being sent up with a header containing the access token:
"Authorization: Bearer "YOUR_ACCESS_TOKEN"If successful we should receive a response object structured like this
And that is the oauth flow! Once we have our access_token and base_uri we have finished our Authentication and we can finally start making hits to the API to create envelopes or any other features from Docusign.
Complex But Secure
At first I thought the flow for Docusign oauth was needlessly complicated. That was until I thought of how important security is for something requiring a digital signature. The extra steps are quite necessary when you think of how malicious things can get with forgery involved. Hopefully this will help you to understand Docusign’s oauth flow.
Happy Coding!
