Permissions required to update user password?

[steev sachs]

I have successfully* set up a call to update a user password using the PUT call to /d2l/api/lp/(version)/users/(userid)/password but am receiving 403 responses, which indicate that the user context does not have appropriate permissions.

My user context (which I've confirmed using whoami) has the "Reset the Users' Passwords in the Edit Tool" permission set, and I've confirmed that this user can successfully change other users' passwords from within D2L (confirmed with the test account I'm trying to change via API).  

Does anyone have suggestions for where I might be missing a dependency or how my call might be going wrong but appearing correct?

For reference, here is the code snippet I'm using:

                $url = $opContext->createAuthenticatedUri( "$scheme://$host/d2l/api/lp/1.0/users/$userId/password/", POST );

$postData = array(

'Password' => $password

);

$postData = json_encode( $postData );

$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, $url );

curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );

curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'PUT' );

curl_setopt( $ch, CURLOPT_POSTFIELDS, $postData );

$result = curl_exec( $ch );

*I am assuming my call is successful because it's returning logical 400 type responses based on whether I call for a nonexistent or existent user.

[Desire2Learn Staff: Viktor]

The appropriate call to update a user's password by providing a new one is:

    PUT /d2l/api/lp/(version)/users/(userId)/password

    {

       "Password": <new password string>

    }

Note that it does not accept a trailing slash, and it is also a PUT route.

Note that the POST route enforces a password reset on the user by sending them the "reset password email". It also does not accept a trailing slash; nor does it accept any body data in the POST body (it's an empty post, that should have Content-Length: 0):

    POST /d2l/api/lp/(version)/users/(userId)/password

Finally, I'm not sure what version of the LMS you're using your client app with, but the 1.0 LP API routes are now currently deprecated, and you should move to a more modern LP API contract if you can. You should look to see what versions of the LP API routes are available on your service, and seek to use a more modern one... as these calls are core functionality that really hasn't changed since our 9.4.1 platform release, I'd recommend that you update your code to call the most recent/modern LP version that your back-end LMS says it can support.

Hope this helps!

[steev sachs]

Thank you for your reply--the fault was a result of several factors, many of which you called out, such as the trailing slash and my submitting PUT as a custom request.  It's now all resolved and working correctly.

FWIW: It's interesting to me that my faulty request was returning logical codes from D2L.  I wonder if there could be better handling to tell you "You're way off track!" 

Also, our development is all on the 1.0 LP route because, bluntly, that's what the examples from D2L use.  I'm initiating a project to bring them up to date on 1.1 now that we have a working solution to improve upon, but it'd be nice to have up to date samples from D2L to begin from.

Thank you again for your help!

[Desire2Learn Staff: Viktor]

I agree with your assessment of the samples,

The right resolution to this process is slightly complicated because of maintainability (how often do we update the examples and at what point? every time a new API contract is released? how many examples then need updating) and "realism" (we could just put a "(version)" placeholder in our examples except where a particular API contract must pertain, but then we'd likely have a certain amount of confusion among clients who insist on being literal with the examples and putting "(version)" in their API calls), and appropriateness -- not all our clients are using the same back-end service, and so the API contracts they have available varies client to client.

Thanks for your feedback -- there might be several ways we could address this general issue, and choosing the right approach will be a task put on the general list of documentation improvements to make.

[steev sachs]

Hi Viktor,

I think the choice to include working samples (rather than using a placeholder) is absolutely the correct one.  

I sympathize with the difficulty of keeping documentation (particularly samples) up to date.  

Maybe I'm overlooking it, but what might be helpful is just an "Updating from 1.0 to 1.1" page in the reference section of the Valence Dev site.

[Desire2Learn Staff: Viktor]

So, at the moment, we have been tracking the features, additions, and changes in our platform's about page: <http://docs.valence.desire2learn.com/about.html#technology-features>.

The documentation includes a fairly detailed list of what's new with the most current in-market release, as well as the detailed changes from the most recent in-market release.

Our platform specifically strives to be additive and backwards compatible as much as possible: this means that once a route works within a product component's 1.0 API contract, we tend to be additive and superset around that call only. So, in nearly all cases, if you made an API call with the 1.0 contract, you can expect to be able to make the same call in future 1.x contract versions with minimal to no changes expected (in some cases, the structures passed back and forth might have additional properties introduced, or the availability of query parameters on the call might be expanded). If you write your code with this in mind, and follow the basic philosophy of "if you don't know how to handle a data element, ignore it", then tracking API calls from version to version, within a major release family (i.e. 1.0 to 1.1 to 1.2) is generally quite safe.

To be sure, you should perform testing against each API contract you want to support, of course, and you can check the reference documentation for the API calls to verify any changes that get made, version to version.

Breaking changes do happen in rare cases: those are documented. And with the release of a new major API contract version (i.e. 1.x --> 2.x), API calls might change much more substantially, not be backwards compatible, or might in fact have functionality offered in a new way or with a new call.