From DocuSign, I'm Cameron Loewen, a member of the developer content team.
In this screencast, I'll walk through how to generate an access token manually using
authorization code grant OAuth 2.0 authentication with Postman on Windows.
You can also automate this process using SDK methods or by duplicating the implementation
from the Quickstart.
Any call to the DocuSign platform APIs requires an access token for authentication.
You can get an access token using one of DocuSign's supported OAuth 2.0 flows-- Auth Code Grant,
JWT Grant, or Implicit grant.
This video focuses on Auth Code Grant.
Auth Code Grant is the recommended OAuth flow for most apps.
Some of the main advantages of this grant are that it is easier to implement than JWT;
the access token that you receive from Auth Code Grant has a lifetime of eight hours,
rather than one from JWT; and you also receive a refreshed token that makes it easy to renew
your access token when it is close to expiration.
If you're looking for more context on when to use the Auth Code Grant or other supported
grant types, you can read more about them in the Developer Center platform documentation,
linked in the resources at the end of this screencast.
To follow along with this video and get an access token, you will need to have these
things first-- an integration key, a redirect URI for your integration key, and a secret
key defined for your integration key.
For a full walkthrough of how to set up an integration for Auth Code Grant authentication,
see Larry Kluger's screencast linked in this slide.
For this screencast, I've set up an app in the development environment.
I can find its integration key in the apps and keys page.
To define other required values, I click Edit, then Add URI to create or redirect URI.
For this example, I will use localhost, because I want to display the authentication response
in my own browser.
Next in the authentication section, I select Add Secret Key.
This creates a new secret key, which I copy and save to a secure place, because I'll need
it in a later step.
Once you've created the required values, go to the bottom of the page and select Save.
Next, I get consent.
In Auth Code Grant, your app will make API calls on behalf of the user, acting as them
to create envelopes and perform actions in the DocuSign APIs.
To do this, your app needs the user's consent by directing the user to authorize your app.
To direct the user to DocuSign to authorize my app and get consent, I will construct a
URI value with a set of query parameters that includes a base path for the authentication
service.
Note that this path changes depending on whether the app is in the development environment
or in production.
I'm using the base URI for the development environment here.
Take a look at the first line of this syntax.
I will also need my apps integration key to add for the client ID parameter; a redirect
URI that matches one of those configured for my app; a list of scopes that my app needs,
separated by spaces-- typically you would use the scope signature for the e-signature
REST API-- and finally, a response type value of code, which tells DocuSign that I'm using
the Auth Code Grant.
Using my integration key and redirect URI, along with the signature scope, I build this
URI.
Once I've built the consent URI, I can open it in the browser.
This will open a window prompting the user to log in and grant signature permission to
my app.
Choose Accept.
Next, DocuSign returns a URI containing an authorization code to the redirect URI that
I specified earlier.
In this example, it is localhost, so it is loaded directly by my browser.
Because the browser cannot render the authorization as a web page, it will show an error message,
which you can ignore.
The URI of the page will contain the authorization code that you need to provide for the code
parameter used in the next step.
I highlight the code and copy it to a secure place before beginning the next step.
Now that I have consent and the authorization code, I can exchange that code for an access
token by sending a POST request to the DocuSign authentication service API.
For this example, I'll use Postman to make the request using the development environment
URI that I've highlighted.
This request has one header and two body data fields.
The header data field is authorization, which contains your apps integration key and a secret
key, separated by a colon character, converted into base64, and prefixed with the word Basic.
In this example, I will use the BTOA function in the Chrome browser's JavaScript console
to convert the combination of my integration key, colon, and secret key into base64, then
copy the resulting value into my Postman authorization header.
The body fields are grant type, which should have the value authorization_code and code,
which contains the authorization code that I just saved.
If the request succeeds, the access token field and their response will contain an access
token that I can use to authenticate my DocuSign API calls.
Note that the Auth Code Grant also returns a refresh token, which you can use to renew
your access token when it is close to expiration, in a manner very similar to exchanging the
authorization code for an access token.
For details on the lifetime and usage of refresh tokens, see the links in the resources at
the end of this screencast.
To make a DocuSign API call, you also need to get the base URI for the calls path for
our user.
To do this, I make a GET call to the OAuth user info endpoint.
This returns a set of information about my user's account, including their base URI and
account ID.
For example, I can copy and paste my newly obtained access token into the authorization
header for this save query that uses my account's base path.
Add the word Bearer and a space in front of it to the token value, and successfully call
the e-signature API.
If you have any questions about how to develop your integration with DocuSign, check our
documentation on the Developer Center.
You can also go to Stack Overflow, reach out to Developer Support, or sign up for API Office
Hours.
Thanks for watching.
If you're watching from our YouTube channel, please post questions and comments below the
video, or email us at developers@docusign.com.