CloudM Automate People API - Setup

Overview

The People API lets you manage CloudM Automate user profiles from an external system — create users, update fields, start offboarding, and read profiles — using a Google service account as the caller.

How authentication works

There are two independent layers, and knowing which is which makes troubleshooting easy:

1. Google identifies the caller. You authenticate as a service account and obtain a short-lived Google access token. CloudM only reads the service account's email from that token — which is why the only delegation scope required is userinfo.email.
2. CloudM authorises the caller. Inside Automate you grant that service account a Role (permissions), scoped to an Organizational Unit. CloudM checks this on every request.

Prerequisites

• A Google Cloud project and admin access to the Google Admin console.
• Admin access to CloudM Automate (Settings > Roles).
• The primary domain your users live under (e.g. yourcompany.com).

Step 1 — Create a service account

In the Google Cloud console, create a service account (Google's guide). A service account is a non-human identity your integration acts as; it doesn't need any project roles for this. Note its email and Unique/Client ID.

Step 2 — Grant domain-wide delegation

Admin console > Security > Access and data control > API controls > Domain-wide delegation > Add new.

• Client ID: the service account's Unique ID.
• Scope (the only one needed): https://www.googleapis.com/auth/userinfo.email
• Save.

Step 3 — Generate an access token

Cloud Shell is recommended — you don't need to install anything locally. In the Google Cloud console, open Cloud Shell (terminal icon, top right):

1. Select the ⋮ (three dots) > Upload and upload your service account JSON key.

2. Run: 

   gcloud auth activate-service-account --key-file=./YOUR_KEY_FILE.json
   gcloud auth print-access-token

3. Copy the token. It is valid for 60 minutes.

Step 4 — Create and assign a CloudM role

In Automate > Settings > Roles:

1. Create role with Global Scope, tick the permissions you need (all permissions for full access), and Save.
2. Role Assignment > Add: set Assign To: Service Account, Name: the exact SA email, and Org Unit: Root (top-level) OU.

Step 5 — Verify the connection

1. Open the Automate v4 SwaggerUI > Authorize.
2. Enter Bearer <your access token> (include the word Bearer and a space) > Authorize.

3. Try a GET on a real user in your verified domain: 

   curl -X GET "https://mycloudpages.appspot.com/_ah/api/people/v4/{DOMAIN}/{USER_EMAIL}" \
     -H "accept: application/json" \
     -H "Authorization: Bearer {ACCESS_TOKEN}"

A 200 with the user's JSON profile means you're set.

Troubleshooting