 |
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 Automate People API v4 can be found here. |
The CloudM Automate People API allows administrators to integrate CloudM Automate 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 Automate API v4
To use the CloudM Automate 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 Automate 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 Automate, 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 Automate SwaggerUI and select Authorize.
- Type 'Bearer generated_access_token' and then click Authorize. You will now be able to access the Automate 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 (Automate 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