How to create a user with Web Services API - Also how to disaable a user, change or update project permssions and remove project permissions for a user

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

What is the payload to create a new user? 

This also contains links on how to disable a user, change project permissions, and remove project permissions for a user

 

Resolution

Creating a user with specific permissions using the API will occur in 2 steps. This article will only discuss creating a user.  Only Subscription Administrators and Workspace Administrators are allowed to create Users.

1. Create the User
2. Update Permissions for the User

For more information on updating project permissions and disabling users, please see:

• How to create or change ProjectPermissions and add TeamMemberships with Web Services API.  Each article below uses a different endpoint and slightly different call types.

  • https://knowledge.broadcom.com/external/article?articleId=47760

  • https://knowledge.broadcom.com/external/article?articleId=374424

• Disable user with Web Services API 
  • https://knowledge.broadcom.com/external/article?articleId=57573 
• How to remove a user's access to a project using Web Services API
  • • https://knowledge.broadcom.com/external/article?articleId=57514 

 

• Creating a new user
  • The curl example below uses API Key authentication to create a user.
    • Follow the same syntax after replacing placeholder "zsessionid:<API Key - include the underscore before the key>" with a valid API Key of a user who has sufficient permissions (subscription or workspace admin) to create new users.
    • The payload must include required fields UserName and EmailAddress:
      • curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"User\":{\"UserName\":\"<User>@<Company.com>\",\"EmailAddress\":\"<User>@<Company.com>\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/User/create
        • NOTE: Username must be unique.
        • Usernames are unique across the entire Rally stack.
        • An attempt to create a new user with a username that already exists results in the following error:
    • {"CreateResult": {"_rallyAPIMajor": "2", "_rallyAPIMinor": "0", "Errors": ["Validation error: User.UserName conflicts with <User>@<Company.com> ", "Validation error: User.UserName conflicts with <User>@<Company.com>"], "Warnings": []}}
      • NOTE: Required fields must be set in the payload.
      • An attempt to create a new user without email address (as in this wrong example):
        • curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"User\":{\"UserName\":\"<User>@<Company.com>\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/User/create
      • results in the following error: 
        • {"CreateResult": {"_rallyAPIMajor": "2", "_rallyAPIMinor": "0", "Errors": ["Validation error: User.EmailAddress should not be null"], "Warnings": []}}
    • If you want to create a user now but activate the user later, the payload can be modified to set?Disabled?attribute to?true:
      • curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"User\":{\"UserName\":\"<User>@<Company.com>\",\"EmailAddress\":\"<User>@<Company.com>\",\"Disabled\":\"true\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/User/create
        • If the operation is successful a full JSON of the newly created user will be returned in the terminal.
  • Here is what this looks like in Postman
    • ENDPOINT URL:
      • https://rally1.rallydev.com/slm/webservice/v2.0/user/create
    • REQUEST TYPE:
      • Post
    • BODY:
    • {
        "User": 
          "UserName": "[e-mail]",
          "EmailAddress": "[e-mail]",
          "DefaultProject": {"_ref": "/project/<ProjectOID>"},
          "Language": "en-US",
          "LastName": "Test1",
          "FirstName": "testAPItest",
          "DisplayName": "testiAPI-Test"
        }
      }
      • ***NOTE: This will only create a user in the system with limited or no access.  This newly created user has Workspace User and Project Viewer permissions according to the subscription administrator's default workspace and project. If no default workspace or project is set or if the Rally UserID creating the new user has no Default Project set, the first open project is chosen alphabetically. The workspace that is associated with that project is chosen as the current default workspace.