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
JSON web token or JWT OAuth 2.0 grant authentication with Postman windows.
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 JWT.
JWT is the only grant that enables you to impersonate an admin or system user,
which is useful for cases when all of your users will require a system or admin login.
If you are looking for more context on when to use JWT Grant or other supported grant types,
you can read more about it in the Developer Center Platform documentation
linked in the resources at the end of this screencast.
This screencast walks through the process of getting an access token with JWT manually.
You can also automate this process using SDK methods or by duplicating the implementation
from the Quickstart. 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 an RSA key pair defined for your integration key.
For a full walkthrough of how to set up an integration for JWT authentication,
see Larry Kluger's screencast linked here. For this screencast, I have set up an app in
the development environment. I can find its integration key in the apps and keys page.
To define the other required values, I click edit, then add URI to create a redirect URI.
For this example, I will use localhost because I want to display the authentication response in
my own browser. Next, I click generate RSA to create a new RSA key pair. These values
are only shown once. So for this example, I will save them to Notepad to use later.
After checking to ensure that I have all the items I need, I can get consent. JWT grant works by
having your app impersonate a user, typically an admin, and making all of your calls as that user.
To do this, you need that person's consent for your app to act as them. To get consent,
I'll construct a URI value that holds 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 the syntax shown. I will also need my application's integration key, which is also
called a client ID, a redirect URI that matches one of those configured for the application
with the specified integration key, a list of scopes that my app needs separated by spaces--
note that typically you would use the scope's signature and impersonation for a signature--
and finally a response type value of code.
Using my integration key and redirect URI along with the signature and impersonation scopes,
I get this URI. Once I have the consent URI, I can open it in the browser. This will open
a window prompting the user to log in and grant signature and impersonation permissions to my app.
Choose accept, then close the browser tab.
In the JWT flow you could ignore the URI returned to localhost and the error
message shown in your browser, which is expected. Now that I have consent,
I need to construct a JSON web token and exchange it for an access token.
A DocuSign JSON web token contains three JSON blocks that are encoded and separated by periods.
I need three pieces of information to create a JSON web token for authenticating a user.
First, consent from the user or administrator of their organization,
which we obtained in the previous step. We also need the integration key, also called
the client ID, and the API username, which is also called the user ID. You can make the token
on your own or use a convenient online tool such as JWT.io. In this screen case, I'll use JWT.io.
In my header, I record the algorithm used to encode data and the type of token I'm creating.
These values should be asked RS 256 and JWT. Next, the token body contains the data for the
claims that my application is making, such as the scopes I request and the lifetime of the token.
The ISS claim holds my app's integration key. The sub claim holds the good API username of
the user to be impersonated. This must match the user who logged in to grant consent to your app.
The AUD claim holds the URI of the authentication service instance to be used. For this screencast,
I'll use the developer environment URI of account-d.docusign.com. For production, use
account.docusign.com. The IAT claim holds the date and time when the token was issued in Unix epoch
format. The EXP claim holds the date time when the token assertion will expire in Unix epoch format.
Finally, the scope claim holds the space separated list of scopes that I'm requesting. The list of
scopes should include only those that you have already obtained consent for in the previous step.
For this example, I will request only the signature scope. The final part of the JSON
web token is the signature. This is a digital signature that enables DocuSign to verify that
the token was created by my application, and that it hasn't been modified since it was created.
For this step, I copy and paste my public and private keys from the RSA key pair that I saved
earlier into the header and payload fields, so that they can be base64 encoded and encrypted.
Make sure to include the begin and end lines for both of the public
and private keys. If my account has been set up, and I've entered my information correctly,
I should now be able to exchange the resulting JSON web token for an access token.
I do this by sending a POST request containing the JSON web token
to the DocuSign authentication service API. For this example,
I'll use Postman to make the request using the development environment URI currently highlighted.
This request has two data fields in the body, grant type, which would have the value shown on
the screen, and assertion, which contains the encoded JSON web token that I just created.
If the request succeeds, the access token field in the response will contain an access token
that I can use to authenticate by DocuSign API calls. To make a Docusign API call,
we also need to get the base URI for the call's path for our user.
To do this, we make a get call to the OAuth user info endpoint. This returns a set of
information about your 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 saved query that uses my accounts base path, add the word bearer
and a space in front of 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 Stackoverflow, 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.