CloudM Manage People API v4 – CloudM

This article is for Version 4 of the People API, which we recommend that you use for any new development.

See this link for the swagger documentation for version 1 for reference.

Swagger documentation for CloudM Manage People API v4 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.

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
DELETE - abort an offboarding workflow.

Refer to the swagger documentation for the full details of the operations available for each endpoint.

Setting up the CloudM Manage API v4

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

Navigate to the following Google Cloud article here: Using OAuth 2.0 for Server to Server Applications
You are going to create a service account following those instructions and then once you reach the domain-wide delegation section, move onto step 2.
Once you get to the steps where you are required to setup Domain-wide Delegation in Google Workspace. The only API scope you need to add here is: https://www.googleapis.com/auth/userinfo.email

If you have already created and saved a JSON key for your service account, you can skip this step. If not, please follow these steps:
- Go to console.cloud.google.com and login with your admin account.
- Navigate to IAM & Admin > Service Accounts and find the newly created service account.
- Click the three vertical dots on the right-side of the service account and click Manage Keys.
- Click the button that says 'Add Key', select Create new key, select JSON and finally select Create. Save the JSON Key in an easily accessible location for future use (in step 9).
Now, open a command prompt on your desktop (Windows Key > R > Type 'cmd' and hit Enter)
Type in the command prompt gcloud auth activate-service-account service_account_you_just_created --key-file *DON'T HIT ENTER YET*
Find the JSON key that you downloaded earlier and drag it onto the command prompt window. It should automatically fill in the file path to the JSON key.
Once you've got something that looks like this: gcloud auth activate-service-account service_account_you_just_created --key-file "C:\Folder\Folder\service-account-id.json" hit Enter
You should see a response saying Activated service account credentials for: [service-account@project.iam.gserviceaccount.com]
Finally, type the following command into the command prompt and take a note of the generated access token. gcloud auth print-access-token
Close the command prompt and navigate to Manage, navigate to Settings > Roles and create a new role.
The role should have Global Scope and all of the permissions available in the list and ensure you Save after assigning the permissions.
Go to Role Assignment; set Assign To: Service Account; set Name: your_service_account; set Org Unit: Root (Top-level) OU; and then click Add.

Now, navigate to the Manage SwaggerUI and select Authorize.
Type 'Bearer generated_access_token' and then click Authorize. You will now be able to access the Manage People v2 API.

Endpoints & Usage

POST: Create User

Request:

curl -X POST "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}" -d @payload.json

payload.json

(Mandatory Fields, more fields can be found in the swagger documentation HERE)

{
 "id": "{EMAIL_ADDRESS}",
 "familyName": "{SURNAME}",
 "givenName": "{FORENAME}",
 "password": "{PASSWORD}"
}

Response:

{
 "hidden": false,
 "email": "{EMAIL_ADDRESS}",
 "id": "{EMAIL_ADDRESS}",
 "onHold": false,
 "parentPath": "{DOMAIN}",
 "suspended": false,
 "familyName": "{SURNAME}",
 "givenName": "{FORENAME}",
 "passwordUpdated": "{CREATION_DATE_AND_TIME}",
 "preventDeprovision": false,
 "manager": ""
 "provisionDate": "string"
}

POST: Schedule Create User

Request:

curl -X POST "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}" -d @payload.json

(Mandatory Fields, more fields can be found in the swagger documentation HERE)

{
 "id": "{EMAIL_ADDRESS}",
 "familyName": "{SURNAME}",
 "givenName": "{FORENAME}",
 "password": "{PASSWORD}"
 "provisionDate": "string"
}

Response:

{
"hidden": false,
"endDate": "string",
"id": "string",
"workflowId": "string",
"onHold": false,
"tags": [
{
"name": "string",
"fontColour": "string",
"backColour": "string"
}
],
"predefinedTags": [
{
"name": "string",
"fontColour": "string",
"backColour": "string"
}
],
"extraInformation": [
{
"id": "string",
"name": "string",
"value": "string",
"type": "TEXT"
}
],
"predefinedExtraInformation": [
{
"id": "string",
"name": "string",
"value": "string",
"type": "TEXT"
}
],
"parentPath": "string",
"additionalName": "string",
"birthday": "string",
"familyName": "string",
"givenName": "string",
"namePrefix": "mr",
"nameSuffix": "string",
"nick": "string",
"sex": "Male",
"notes": "string",
"maidenName": "string",
"shortName": "string",
"employeeId": "string",
"preferredName": "string",
"subject": "string",
"aliases": [
"string"
],
"occupation": "string",
"addresses": [
{
"type": "WORK",
"value": "string",
"primary": false
}
],
"phoneNumbers": [
{
"type": "MOBILE",
"value": "string",
"primary": false
}
],
"webSites": [
{
"type": "BLOG",
"value": "string",
"primary": false
}
],
"emails": [
{
"type": "GENERAL",
"value": "string",
"primary": false
}
],
"manager": "string",
"assistants": [
"string"
],
"events": [
{
"type": "ANNIVERSARY",
"value": "string",
"primary": false
}
],
"imAddresses": [
{
"type": "AIM",
"value": "string",
"primary": false
}
],
"locations": [
{
"area": "string",
"buildingId": "string",
"deskCode": "string",
"floorName": "string",
"floorSection": "string",
"type": "string",
"customType": "string"
}
],
"department": "string",
"employmentType": "string",
"jobDescription": "string",
"name": "string",
"title": "string",
"costCentre": "string",
"hireDate": "string",
"password": "string",
"provisionDate": "string"
}

POST: Partially Update a User

Request:

curl -X POST "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}/{USER_ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}" -d @payload.json

payload.json

{
 "onHold": true
}

Response:

{
"hidden": false,
"email": "{EMAIL_ADDRESS}",
"id": "{EMAIL_ADDRESS}",
"onHold": true,
"parentPath": "{DOMAIN}",
"suspended": false,
"familyName": "{SURNAME}",
"givenName": "{FORENAME}",
"passwordUpdated": "{PASSWORD_DATE_AND_TIME}",
"preventDeprovision": false,
"manager": ""
}

POST: Offboard a User

Request:

curl -X POST "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}/{USER_ID}/offboard" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}" -d ""

Response:

{
"hidden": false,
"email": "{EMAIL_ADDRESS}",
"id": "{EMAIL_ADDRESS}",
"workflowId": "{WORKFLOW_ID}",
"onHold": false,
"parentPath": "{DOMAIN}",
"suspended": false,
"familyName": "{SURNAME}",
"givenName": "{FORENAME}",
"passwordUpdated": "{PASSWORD_DATE_AND_TIME}",
"deprovisioned": "{OFFBOARDING_DATE_AND_TIME}",
"preventDeprovision": false,
"manager": ""
}

GET: Fetch User Data

Request:

curl -X GET "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}/{USER_ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}"

Response:

{
  "hidden": false,
  "endDate": "string",
  "id": "string",
  "workflowId": "string",
  "onHold": false,
  "tags": [
    {
      "name": "string",
      "fontColour": "string",
      "backColour": "string"
    }
  ],
  "predefinedTags": [
    {
      "name": "string",
      "fontColour": "string",
      "backColour": "string"
    }
  ],
  "extraInformation": [
    {
      "id": "string",
      "name": "string",
      "value": "string",
      "type": "TEXT"
    }
  ],
  "predefinedExtraInformation": [
    {
      "id": "string",
      "name": "string",
      "value": "string",
      "type": "TEXT"
    }
  ],
  "parentPath": "string",
  "additionalName": "string",
  "birthday": "string",
  "familyName": "string",
  "givenName": "string",
  "namePrefix": "mr",
  "nameSuffix": "string",
  "nick": "string",
  "sex": "Male",
  "notes": "string",
  "maidenName": "string",
  "shortName": "string",
  "preferredName": "string",
  "subject": "string",
  "aliases": [
    "string"
  ],
  "occupation": "string",
  "addresses": [
    {
      "type": "WORK",
      "value": "string",
      "primary": false
    }
  ],
  "phoneNumbers": [
    {
      "type": "MOBILE",
      "value": "string",
      "primary": false
    }
  ],
  "webSites": [
    {
      "type": "BLOG",
      "value": "string",
      "primary": false
    }
  ],
  "emails": [
    {
      "type": "GENERAL",
      "value": "string",
      "primary": false
    }
  ],
  "manager": "string",
  "assistants": [
    "string"
  ],
  "events": [
    {
      "type": "ANNIVERSARY",
      "value": "string",
      "primary": false
    }
  ],
  "imAddresses": [
    {
      "type": "AIM",
      "value": "string",
      "primary": false
    }
  ],
  "locations": [
    {
      "area": "string",
      "buildingId": "string",
      "deskCode": "string",
      "floorName": "string",
      "floorSection": "string",
      "type": "string",
      "customType": "string"
    }
  ],
  "department": "string",
  "employmentType": "string",
  "jobDescription": "string",
  "name": "string",
  "title": "string",
  "hireDate": "string",
  "provisionDate": "string",
  "password": "string"
}

DELETE: Abort Offboarding Workflow (Manage People API v1)

Request:

curl -X DELETE "https://mycloudpages.appspot.com/_ah/api/people/v1/workflows/{DOMAIN}/{WORKFLOW_ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}"

Response:

Status: 204 No Content