![]() |
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.
Available Functionality
Currently the following verbs/operations are supported;
- POST - create a new user profile, update (patch) one or more fields of an existing user profile, start offboarding an existing user
- PUT - update (replace) an existing user profile
- GET - fetch an existing user profile
Refer to the swagger documentation for the full details of the operations available for each endpoint.
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:
- Create a Role in CloudM Manage with all permissions enabled, and assign the role to Service Account.
- Log into your admin account for the domain and navigate to: https://developers.google.com/oauthplayground
- Input https://googleapis.com/auth/userinfo.email into your OAuth scopes and select Authorise APIs.
- 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:
- 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.
-
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.
Managing OAuth
For detailed information regarding managing the OAuth process for using the CloudM Manage People API, please refer to the standard Google documentation which can be found here and contains examples for various platforms.
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
Comments
0 comments
Please sign in to leave a comment.