Clarification on REST APIs around user management

Question

I recently created a docusign developer account and integrator key and was playing with docusign REST APIs and had some questions

1. I can retrieve full list of users under my account by using following REST call. https://demo.docusign.net/restapi/v2/accounts/<accountid>/users?additional_info=true

   However if I try and retrieve a specific user (other than the one I am passing in my X-Docusign-authentication) header i get http 400 error with message that the "Invalid UserId. UserId specified in request uri does not match authenticated user"

   https://demo.docusign.net/restapi/v2/accounts/<accountid>/users/0d51a699-b17a-48b7-95b6-1e9e9806deb6

   In both cases i am sending the following header.

   X-DocuSign-Authentication: <DocuSignCredentials><Username>{0}</Username><Password>{1}</Password><IntegratorKey>{2}</IntegratorKey></DocuSignCredentials>

   I am surprised that while I can read all users fine, I cannot just read one specific user. Surely it doesn't seem like this is security thing since I can read the user via one API but not the other using the same auth token.

   What am i missing?

   I guess I can go the route of SOBO (Send on behalf of functionality), but I wanted to confirm if above behavior is expected.

Update#1

: I went the SOBO approach and now i get a different error (USER_NOT_ACCOUNT_ADMIN) as shown below

GET /restapi/v2/accounts/{accountid}/users/0fe29a55-5564-42a9-b09d-cbe699db13dd HTTP/1.1
Authorization: bearer {token for authenticating user}
X-DocuSign-Act-As-User: {operating user's email}
Accept: application/json
Host: demo.docusign.net
Connection: Keep-Alive

HTTP/1.1 401 Unauthorized
Cache-Control: no-cache
Content-Length: 100
Content-Type: application/json; charset=utf-8
Date: Thu, 17 Oct 2013 21:18:32 GMT
Strict-Transport-Security: max-age=7776000; includeSubDomains

{
  "errorCode": "USER_NOT_ACCOUNT_ADMIN",
  "message": "User is not an account administrator."
}

I also tried the second SOBO approach of getting a oauth token for the operating user but got back http 400 error with below message

{
  "error": "invalid_request",
  "error_description": "An OAuth2 error occurred."
}

So while i can get an oauth token for the autheitcating user, i am not able obtain oauth token for the operating user or act on their behalf.

I have made sure that authenticating user is "Account Administrator" and has both "apiAccountWideAccess" and "•allowSendOnBehalfOf" set to true. The only thing set to "false" is "canSendAPIRequests". My account id in sandbox environment is "601565a7-e9c7-463b-9d7c-622aed905ea8" Any ideas?

Update#2

Instead of generating oauth tokens on behalf of both authenticating user and operating user, i tried passing below header and i can finally get another user's profile and update another user's profile.

X-DocuSign-Authentication: <DocuSignCredentials><SendOnBehalfOf>{operating userid}</SendOnBehalfOf><Username>{authenticating userid}</Username><Password>{authenticating user's password}</Password><IntegratorKey>{developer's integrator key}</IntegratorKey></DocuSignCredentials>

Great! So here is status of what works and what doesn't.

Works with no SOBO header anywhere

GET /restapi/v2/accounts/357938/users?additional_info=true // Read all users  
GET /restapi/v2/accounts/357938/users?email=[e-mail]&additional_info=true // Read single user by email
POST /restapi/v2/accounts/357938/users // Add users
DELETE /restapi/v2/accounts/357938/users // Close users    

*Works with SOBO in X-DocuSign-Authentication header

PUT /restapi/v2/accounts/357938/users/74a021e1-3090-4843-b9ab-cceb7cd119f4/profile // Update user's profile
GET /restapi/v2/accounts/357938/users/74a021e1-3090-4843-b9ab-cceb7cd119f4/profile // Read user's profile

Still doesn't work with or without SOBO**

GET /restapi/v2/accounts/357938/users/74a021e1-3090-4843-b9ab-cceb7cd119f4/settings 
GET /restapi/v2/accounts/357938/users/74a021e1-3090-4843-b9ab-cceb7cd119f4

In both not working cases i get following error

• Without SOBO i get error that userid doesn't match autheitcating user.
• With SOBO i get error than user is not an account admin

I would very much appreciate any help in resolving the not working cases. I can provide more detaisl as needed.

1. Secondly I want to implement a scenario where I can deactivate a user in an account so they can no longer log into docusign. And subsequently I would like to enable that user back again with same permission that they had before they were disabled.

   I see that user has a "userStatus" field and was wondering if I can use that to de-activate the user and then re-activate if needed. If this is supported then what value would correspond to deactivating the user?

   The other thing I note is that on DELETE a user, the user is only soft-deleted since I can still query the user with the status "CLOSED". That would solve my "deactivate" problem. However I was not sure if there is a way to reactivate them back again after the user has been "closed"?

Answer 1

I believe this might be an account administration issue. I'm not sure why but I looked at your account settings from DocuSign's side and I saw the "Send on Behalf of" was not checked on your account- which is weird since it seems you have access to the setting in your Console -> Preferences settings.

But in either case I'm wondering if the setting I just enabled on your account has solved your issue, as it might have.

I'm also not sure about the user info portion of your question, let me see if I can come up with anything for that and I'll edit my answer once I do.

Answer 2

In reply to Erign's post above.

Anyone who is an account admin should be able to modify/add/delete users in an account. I'm not sure if your SOBO steps are correct though, can you confirm that you are following THESE STEPS exactly? If so, at which step do you run into issues or get an error?– Ergin5 mins ago

Yes i am following those steps. I am able to generate oauth token for the autheitcating user , but get an error when doing the same for the operating user. Below are my request and responses.

1. REQUEST FOR AUTH TOKEN FOR AUTHENTICATING USER

POST /restapi/v2/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: demo.docusign.net
Content-Length: 139
Expect: 100-continue
Connection: Keep-Alive

grant_type=password&client_id={integratorykey}&username={authenticating user's email}&password={authenticating user's password}&scope=api

RESPONSE

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 100
Content-Type: application/json; charset=utf-8
Date: Thu, 17 Oct 2013 22:57:26 GMT
Strict-Transport-Security: max-age=7776000; includeSubDomains

{
  "access_token": "{authenticating user's token}",
  "token_type": "bearer",
  "scope": "api"
}

2. REQUEST FOR AUTH TOKEN FOR OPERATING USER

POST /restapi/v2/oauth2/token HTTP/1.1
Authorization: bearer {authenticating user's token}
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: demo.docusign.net
Content-Length: 137
Expect: 100-continue

grant_type=password&client_id={integratorykey}&username={operating user's id}&password={empty}&scope=api

RESPONSE

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Content-Length: 87
Content-Type: application/json; charset=utf-8
Date: Thu, 17 Oct 2013 22:57:29 GMT
Strict-Transport-Security: max-age=7776000; includeSubDomains

{
  "error": "invalid_request",
  "error_description": "An OAuth2 error occurred."
}