CloudM Automate People API - Building an integration

From testing to a real integration

The setup article had you paste a gcloud-generated token into Swagger. That's perfect for testing, but access tokens expire after 60 minutes, so it can't drive an automated sync. For an integration, your code must generate its own token from the service account key each time it needs one (or let an auth library refresh it for you). Everything else — the endpoints, the role, the domain-wide delegation — stays exactly as you set it up.

Generating a token programmatically

You don't impersonate a user — the integration acts as the service account's own identity (the same identity CloudM matched to your role), requesting only the userinfo.email scope. The cleanest approach uses Google's auth library, which refreshes the token automatically so you never hit the 60-minute wall.

This example uses the google-auth and requests libraries (pip install google-auth requests):

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

KEY_FILE = "service-account-key.json"        # store securely - see Security below
SCOPES   = ["https://www.googleapis.com/auth/userinfo.email"]
BASE     = "https://mycloudpages.appspot.com/_ah/api/people/v4"
DOMAIN   = "yourcompany.com"

# Authenticate once. AuthorizedSession refreshes the access token as needed.
creds   = service_account.Credentials.from_service_account_file(KEY_FILE, scopes=SCOPES)
session = AuthorizedSession(creds)

# READ - fetch a user
resp = session.get(f"{BASE}/{DOMAIN}/user@yourcompany.com",
                   headers={"Accept": "application/json"})
print(resp.status_code, resp.json())

# WRITE - patch a field (partial update)
resp = session.post(f"{BASE}/{DOMAIN}/user@yourcompany.com",
                    json={"onHold": True})
print(resp.status_code, resp.json())

Read and write differ only by HTTP verb and body. For other languages, follow Google's server-to-server OAuth2 guide; the principle is identical.

Endpoint reference (v4)

Base URL: https://mycloudpages.appspot.com/_ah/api/people/v4

The full field list for each payload is in the v4 Swagger reference.

Token refresh & error handling

• Token lifetime: ~60 minutes. AuthorizedSession (above) refreshes automatically; if you generate raw tokens yourself, refresh proactively or on a 401.
• Handle these responses:
  • 401 Valid user credentials are required — token expired or invalid, or you're targeting a user in a domain the service account isn't delegated for. Refresh the token and check the domain.
  • 403 securityException — authenticated, but the service account's role doesn't grant the action for that user's OU. Confirm the role permissions and that it's assigned at the Root OU.
• Build in retries for transient 5xx and for the 401-after-expiry case.

Security

• The service account JSON key is a credential — store it in a secrets manager (not in source control or a shared drive), restrict read access, and rotate it periodically.
• Google now recommends Workload Identity Federation over downloaded keys where possible (why). Key-based auth is the documented path today, but Workload Identity Federation is the more secure long-term option for customers who want to adopt it.

HR system integrations

A common use case is syncing an HR system (e.g. Workday) into CloudM. CloudM normally picks up changes that land in the Google tenant. If your HR system doesn't push into Google (a common gap), this API is how you close that loop — your middleware reads from the HR system and calls these endpoints to create, update, or offboard users in CloudM directly.

Map your HR events to verbs: