Example: User Management REST API

This example shows how to use the cloud operations User Management REST API to manage the lifecycle of a user on a cloud subscription.

The example takes you through checking the user doesn't already exist, inviting one or more users to the subscription, updating user information, and finally deleting the user from the subscription.

Before you begin

All API calls require a valid cross site forgery request (CSRF) token in the IBM®-CSRF-TOKEN header of the call. Obtain a CSRF token by using POST /instance/services/csrf_token. For more information, see Preventing cross site request forgery.

Manage the user lifecycle

Display a list of the users registered on the subscription.
Before you invite a user, you might want to ensure that the user doesn't already exist in the system. To make it easier to scan the list of users, you can add sort criteria to the call. The following call displays the users in the subscription alphabetically in descending order by family name:
```
GET /instance/services/users?sort=family_name:desc
```
Alternatively, if you know that the user you want to invite is called John Smith, you could include a search term to filter the list to show only users with John in the name:
```
GET /instance/services/users?search_term=John
```
If no users match the search term, the JSON object returned by the call contains an empty list.
To display additional information about the users, such as the groups they belong to, add the corresponding value to the optional_parts parameter to the call. Separate multiple optional parts with a comma. Be aware that this parameter can significantly affect the performance of the call and you should use it in combination with search terms or paging. For example,
```
GET /instance/services/users?search_term=John&optional_parts=details,groups
```
Invite a user, for example John Smith, to the subscription by using the following call:
```
POST /instance/services/users
```
The user information is passed in as a JSON object in the request body of the call. For example, to invite a new user, the body of the call must contain at least the user ID:
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
}
```
You can include additional user information by setting the corresponding properties in the JSON object. For example,
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com",
  "email": "john.smith@host.com",
  "given_name": "John",
  "family_name": "Smith",
  "groups": [
    {
      "name": "Participants"
    }
  ],
  "details": {
    "phone_number": "555-555-8377",
    "preferred_language": "de"
  }
}
```
You can customize the basic invitation call in several ways. Here are some examples:
- Skip email invitations
  By default, when users are invited to the cloud subscription, they automatically receive an invitation email for activating their user account. You might want to skip sending these emails, for example, so that you can assign the roles and permissions users need before they activate their accounts. To skip the emails, add the skip_email parameter to the call:
```
POST /instance/services/users?skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
  When you're finished setting up the user accounts, you can send the activation emails by issuing the API call again with the skip_email parameter set to false.
- Activate users accounts automatically
  Depending on how your cloud subscription was set up, it might be enabled for Security Assertion Markup Language (SAML) authentication. With SAML authentication, you can activate user accounts automatically. If you choose automatic activation, you must also skip sending activation emails as shown in the following call:
```
POST /instance/services/users?activate_automatically=true&skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
- Add group information
  Depending on how your subscription was set up, users are automatically assigned to your default groups, for example, Participants for the production environment. If users aren't assigned to groups automatically, you can add the group information in the API call:
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
   "groups": [ 
   {
    "name": "Participants"
   }
  ]
}
```
  If you don't know which groups users should be belong to, you can assign them later by using the Group Management API.
- Invite several users
  To invite several users, use the following call and include the users in the JSON object in the body of the call. This call is useful if you want to bulk import users from your on-premises user registry to the cloud platform user registry. For example,
```
POST /instance/services/bulk/users
...
{
  "users": [
    {
      "user_id": "john.smith@host.com"
    },
    {
      "user_id": "jane.smith@host.com"
    }
  ]
}
```
Update user information.
You can update the user information in the following ways:
- Send the complete JSON object, including the changed properties, with the call. For example, if you wanted to change John Smith's telephone number, you can use the following call:
```
PUT /instance/services/users/john.smith@host.com
...
{
  "user_id": "john.smith@host.com",
  "email": "john.smith@host.com",
  "given_name": "John",
  "family_name": "Smith",
  "groups": [
    {
      "name": "Participants"
    }
  ],
  "details": {
    "phone_number": "555-555-8321",
    "preferred_language": "de"
  }
}
```
  The stored user information is completely replaced with the information that is sent in the request body. If you omit properties from the JSON object, for example, if the groups property is not included in the body, the user will be removed from all groups.
- Merge the updated properties with the stored user information. For example, to change the phone number and add the user to the Operators group, but keep all other user information the same, use the following REST API call:
```
PUT /instance/services/users/john.smith@host.com?update_mode=merge
...
{
  "groups": [
    {
      "name": "Operators"
    }
  ],
  "details": {
    "phone_number": "555-555-8321"
  }
}
```
Delete a user from an subscription.
For example, to delete John Smith from the subscription, use the following call:
```
DELETE /instance/services/users/john.smith@host.com
```