CloudM Manage People API v2

This article is for Version 2 of the People API, which we recommend that you use for any new development. Version 1 is now deprecated, and access will be removed in a later release, so we would encourage you to upgrade as soon as possible. See this link for the swagger documentation for version 1 for reference. Swagger documentation for CloudM Manage People API v2 can be found here.

The CloudM Manage People API allows administrators to integrate CloudM Manage into third party systems, allowing you to centralize your organizational policies with our extensive features and automated tools. For access to the sample client app described below or for further information please contact the support team.

Setting up the CloudM Manage API v2

To use the CloudM Manage People API v2, you must create a service account within the domain. To set this up:

1. Create a Role in CloudM Manage with all permissions enabled, and assign the role to Service Account.

2. Log into your admin account for the domain and navigate to: https://developers.google.com/oauthplayground
3. Input https://googleapis.com/auth/userinfo.email into your OAuth scopes and select Authorise APIs.

4. Once you have authorised the APIs, you will be presented with an Auth code and a button to exchange the authorisation code for tokens. Press this button and you will see the two empty fields now populated. Copy the Access token as seen below:

5. Navigate to https://mycloudpages.appspot.com/api/swagger-ui/index.html#/ . Once there, click the green Authorize button in the top right corner and enter the word “Bearer” followed by your token in the format 'Bearer your_token' and click Authorize.

6. From here, you can now use the predefined commands such as POST, GET and PUT. The relevant fields for each command are specified in the Swagger UI. Each command has different required fields that must be adjusted within the code block. 

Remote methods

Java version

The API methods are wrapped in a java client library. They are grouped in the following stub classes inside the library:

• People.Users
• People.Workflows

Please refer to the classes for information about the methods in the corresponding class.

REST version

people.users.get

Request:

GET people/v2/{DOMAIN}/{USER_EMAIL}

Response:

{
 "endDate": "YYYY-MM-dd",
 "email": {USER_EMAIL}
 "id": {USER_EMAIL},
 "onHold": {BOOLEAN}
 "workflowId": {String}
}

people.users.patch

Update one or more fields of an existing user profile.  The fields to be updated are specified in the body of the request, other fields in the profile are left unmodified. See the swagger documentation for a full list of the fields that can be specified for a profile.

Note: the verb that must be specified is POST, rather than PATCH, although semantically, this is a PATCH operation.

Any collections (e.g. tags, extra information, emails, addresses, websites etc) that are specified in the request, will replace the existing collections on the profile.

Example request

This example adds some tags and extra information to a an existing user’s profile (these tags and extra information will replace any existing tags and extra information in the user’s profile)

POST people/v2/{DOMAIN}/{USER_EMAIL}

{
 "endDate": "YYYY-MM-dd",
 "onHold": true
}

"tags": [
      {
        "name": "my first tag",
        "fontColour": "000000",
        "backColour": "ffdd44"
      },
      {
        "name": "my second tag with default colours"
      }
    ],
    "extraInformation": [
      {
        "name": "Employee ID",
        "value": "X3297"
      },
      {
        "name": "Favourite colour",
        "value": "Red"
      }
    ]
}

Response:

{
 "endDate": "YYYY-MM-dd",
 "email": {USER_EMAIL}
 "id": {USER_EMAIL},
 "onHold": {BOOLEAN}
 "workflowId": {String}
}

people.users.offboard

Begins offboarding the specified user account.

Note: The body of the request is blank for this operation.

Request

GET people/v2/{DOMAIN}/{USER_EMAIL}/offboard

Response:

{
 "endDate": "YYYY-MM-dd",
 "email": {USER_EMAIL}
 "id": {USER_EMAIL},
 "onHold": {BOOLEAN}
 "workflowId": {String}
}

people.workflows.abort

Aborts the offboarding workflow for a user account that was previously triggered via the people/v2/{DOMAIN}/{USER_EMAIL}/offboard endpoint.

Note: the {WORKFLOW_ID} parameter is the value returned in the workflowId field of the response from the previously triggered offboarding operation.

Request

DELETE people/v2/workflows/{DOMAIN}/{WORKFLOW_ID}

Response:

204 No Content