Certain REST API endpoints require UserKey instead of UserName

Summary

In Jira's REST API, there are certain endpoints which accept and require a user's UserKey (represented in the database as app_user.user_key) as an input parameter or argument.

However, the documentation suggests that the parameter should be the user's UserName, which is not necessarily the same value as the user's UserKey. In general, a user's UserKey is the first username that they were ever created with; if in the future, the user were to have their username changed for any reason, their UserKey will still be the original, first value.

This can confuse Admins and Users who try to use these REST API endpoints by providing a UserName (likely the value which they use to log in with, for example), and find that the endpoints do not function correctly.

Furthermore, the UserKey is not visible in Jira's UI. Admins can only find the UserKey by:

• Querying against the database against the app_user database table
• Using the Get User REST API endpoint, which does accept UserName, and returns the UserKey as a value (key)
  • $JIRA_URL/rest/api/2/user?username=<User_Name>

Steps to Reproduce

1. Create a new Jira user (i.e. UserName = test)
2. Immediately change their username (i.e. UserName = newtest)
3. Add them to a Project Role in any project
4. Attempt to use the Delete Actor method for the api/2/project/ {projectIdOrKey}

   /role endpoint to remove them from the Project Role

Expected Results

An HTTP 204 is returned per the REST API documentation, and the user is no longer in the Project Role for the project in question.

Actual Results

An HTTP 204 is returned, but the user is still there in the Project Role for the project in question. No information is provided to the admin clearly demonstrating what has gone wrong.

Workaround

The behavior of the REST API endpoints which demonstrate this behavior cannot be changed. Instead, Admins and Users must first identify the UserKey through either of the methods described above before using these endpoints.

• Querying against the database against the app_user database table
• Using the Get User REST API endpoint, which does accept UserName, and returns the User Key as a value
  • $JIRA_URL/rest/api/2/user?username=<User_Name>