DocuSign JWT Grant how to get GUID userId of the user to impersonate?

Question

I am doing service integration with DocuSign platform using JWT Grant auth type. DocuSign account has multiple users setup.

My service is SendEnvelopService and one of the important request param to the service is user email. SendEnvelopService need to impersonate user with given email-id when calling DocuSign and send envelope in behalf of that user. Note that every request to SendEnvelopService will have different value of email request param.

I have following questions around it -

Question#1) Since I need to impersonate different user every time (based on email id in my request), I assume I need to get new JWT auth token every time, before making actual api call. Is that right? Is it usual and ok to request new JWT auth token so frequently before every api call? Does it raise any integration concerns with DocuSign?

Question#2) In my request, I have email id of the user to impersonate. I don't have user's GUID which I need, to get JWT auth token and impersonate it. Is there any api that I can use to get user GUID by email id? I wonder what kind of authentication will be needed for such api because I don't have JWT auth token yet.

One idea I have is may be I need to setup one admin user in DocuSign and keep admin userId (GUID) in application config. Now I have 2 users, one is admin user and another is request user which I have email from the service request. I can following steps -

1. Do requestJWTUserToken impersonating admin user. We get oAuthTokenAdmin

2. Using oAuthTokenAdmin make https://developers.docusign.com/esign-rest-api/reference/Users/Users/list api call to get userId (GUID) of request user email.

3. Now do another requestJWTUserToken impersonating request userId. We get oAuthTokenUser

4. Now make actual api call using oAuthTokenUser and to send envelope

Answer 1

You're correct that you'll need a new access token for each of your incoming requests since access tokens include a reference to the user object.

If you can cache the email address/access token for its lifetime of one hour, that would be good. And it would save you the time of obtaining a new access token.

Re email to user GUID mapping

Yes, use the API (with an admin access token) to lookup the GUID for an email address. Since the GUID doesn't change, you can (should) store the email/GUID mapping in your app's database. Use the database for the lookups and the API if the lookup fails.

Answer 2

You can add two steps to the JWT authorization flow to query the user ID.

The redirect to the /oauth/auth (step 1) request will contain a code query parameter. This is a JWT that can be used in an /oauth/token request (grant type authorization_code) documented here:

https://developers.docusign.com/platform/auth/authcode/confidential-authcode-get-token/#RequestCode

The response to the /oauth/token request will contain an access token that can be used to make a /oauth/userinfo request. The sub prop in the response is the user ID.

https://developers.docusign.com/platform/auth/reference/user-info/

Once you have sub, you have everything you need to create a JWT and request a new access token.

Answer 3

Go to: https://admindemo.docusign.com/ Log in with your demo (sandbox) credentials. Then you have two options:

If it is only for you, simple thing is to click "API and Keys" page under Integrations on the left nav. You will see this:

You can also click on "Users" on the left and select the user you want, any user really, doesn't have to be you. then you'll see it under this:

For your first question, no, you don't have to do that. You can use the same user for all API calls. Especially if this user is an admin, then you can do all API calls under that context.