Google Cloud User Management API Guide

Auth method: OAuth 2.0 (service account with domain-wide delegation, or user OAuth flow)

Setup steps

1. Create a Google Cloud project in the Google Cloud Console (console.cloud.google.com).
2. Enable the Admin SDK API for the project under APIs & Services > Library.
3. Create a Service Account under IAM & Admin > Service Accounts; download the JSON key.
4. In the Google Admin console (admin.google.com), go to Security > API Controls > Domain-wide Delegation.
5. Add the service account client ID and grant the required OAuth 2.0 scopes.
6. In code, use the service account credentials with subject impersonation set to a super-admin email to call the Directory API.

Required scopes

List Users

• Method: GET
• URL: https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=100&pageToken={token}
• Watch out for: Use customer=my_customer to scope to your own domain. Without domain or customer param, the request fails. nextPageToken must be passed as pageToken in subsequent requests.

Request example

GET /admin/directory/v1/users?customer=my_customer&maxResults=100
Authorization: Bearer {access_token}

Response example

{
  "kind": "admin#directory#users",
  "nextPageToken": "abc123",
  "users": [
    {"id": "1234", "primaryEmail": "user@example.com",
     "name": {"fullName": "Jane Doe"}}
  ]
}

Get User

• Method: GET
• URL: https://admin.googleapis.com/admin/directory/v1/users/{userKey}
• Watch out for: userKey can be the user's primary email, alias email, or immutable Google ID. Using the immutable ID is safest for updates.

Request example

GET /admin/directory/v1/users/user@example.com
Authorization: Bearer {access_token}

Response example

{
  "id": "1234567890",
  "primaryEmail": "user@example.com",
  "name": {"givenName": "Jane", "familyName": "Doe"},
  "suspended": false,
  "orgUnitPath": "/Engineering"
}

Create User

• Method: POST
• URL: https://admin.googleapis.com/admin/directory/v1/users
• Watch out for: Password is required. Domain must be verified and owned by the organization. New users may take up to 24 hours to propagate across all Google services.

Request example

POST /admin/directory/v1/users
Content-Type: application/json
{
  "primaryEmail": "newuser@example.com",
  "name": {"givenName": "New", "familyName": "User"},
  "password": "SecurePass123!"
}

Response example

{
  "id": "9876543210",
  "primaryEmail": "newuser@example.com",
  "name": {"fullName": "New User"},
  "creationTime": "2024-01-15T10:00:00.000Z"
}

Update User (partial)

• Method: PATCH
• URL: https://admin.googleapis.com/admin/directory/v1/users/{userKey}
• Watch out for: PATCH is preferred over PUT for partial updates. PUT replaces the entire user object and requires all required fields.

Request example

PATCH /admin/directory/v1/users/user@example.com
Content-Type: application/json
{
  "name": {"givenName": "Updated"},
  "orgUnitPath": "/Sales"
}

Response example

{
  "id": "1234567890",
  "primaryEmail": "user@example.com",
  "name": {"givenName": "Updated", "familyName": "Doe"},
  "orgUnitPath": "/Sales"
}

Delete User

• Method: DELETE
• URL: https://admin.googleapis.com/admin/directory/v1/users/{userKey}
• Watch out for: Deleted users are moved to a 20-day recovery window before permanent deletion. Data can be transferred before deletion using the Data Transfer API.

Request example

DELETE /admin/directory/v1/users/user@example.com
Authorization: Bearer {access_token}

Response example

HTTP 204 No Content

Suspend User

• Method: PATCH
• URL: https://admin.googleapis.com/admin/directory/v1/users/{userKey}
• Watch out for: Suspended users immediately lose access to Google services but their account and data are retained. Licenses continue to be consumed.

Request example

PATCH /admin/directory/v1/users/user@example.com
Content-Type: application/json
{"suspended": true}

Response example

{
  "id": "1234567890",
  "primaryEmail": "user@example.com",
  "suspended": true
}

Make User Admin

• Method: POST
• URL: https://admin.googleapis.com/admin/directory/v1/users/{userKey}/makeAdmin
• Watch out for: This is a dedicated endpoint for toggling super-admin status. Setting isAdmin via PATCH on the user object does not reliably change admin status.

Request example

POST /admin/directory/v1/users/user@example.com/makeAdmin
Content-Type: application/json
{"status": true}

Response example

HTTP 204 No Content

List Group Members

• Method: GET
• URL: https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members
• Watch out for: Requires admin.directory.group.readonly scope at minimum. Nested group membership is not expanded by default; use includeDerivedMembership=true query param.

Request example

GET /admin/directory/v1/groups/eng-team@example.com/members
Authorization: Bearer {access_token}

Response example

{
  "kind": "admin#directory#members",
  "members": [
    {"email": "user@example.com", "role": "MEMBER", "type": "USER"}
  ]
}

• Rate limits: Admin SDK Directory API enforces per-project and per-user quotas. Default quota is 2,400 queries per minute (QPM) per project for most user operations. Quota increases can be requested via Google Cloud Console.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: HTTP 429 or 403 with reason 'rateLimitExceeded' or 'userRateLimitExceeded' is returned when quota is exceeded. Implement exponential backoff. Quota increases are requestable through the Google Cloud Console quota page.
• Pagination method: token
• Default page size: 100
• Max page size: 500
• Pagination pointer: pageToken

• Webhooks available: Yes
• Webhook notes: Google Admin SDK supports push notifications (webhooks) via the Reports API and Directory API watch endpoints. Clients register a HTTPS receiver URL to receive change notifications for directory resources.
• Alternative event strategy: Google Cloud Pub/Sub can be used as an alternative to direct HTTPS webhooks for more reliable event delivery. Cloud Audit Logs also captures admin activity and can be exported to Pub/Sub or BigQuery.
• Webhook events: users (directory watch), groups (directory watch), admin activity events (Reports API), login events (Reports API), token events (Reports API)

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Cloud Identity Premium ($7.20/user/month)

• Endpoint: Configured per third-party IdP (e.g., Okta, Entra ID) pointing to Google Cloud Identity as the SCIM target. Google Cloud Identity acts as the SCIM service provider; the IdP is the SCIM client.

• Supported operations: Create user (POST /Users), Update user (PATCH /Users/{id}), Deactivate/suspend user (PATCH active=false), Delete user (DELETE /Users/{id}), List users (GET /Users), Get user (GET /Users/{id}), Create group (POST /Groups), Update group membership (PATCH /Groups/{id}), Delete group (DELETE /Groups/{id})

Limitations:

• SCIM provisioning requires Cloud Identity Premium; not available on Cloud Identity Free tier
• SSO must be configured as a prerequisite for SCIM provisioning
• Google Cloud Identity acts as SCIM service provider only; it does not push SCIM to external systems natively
• Custom SCIM attribute mappings are limited to supported directory attributes
• SCIM endpoint URL and bearer token are generated per IdP integration in the Admin console

Three integration patterns cover the majority of production use cases:

Provision and assign to OU: POST to /users with primaryEmail, name, password, and orgUnitPath. Store the returned immutable id. If orgUnitPath is omitted, the user lands in the root OU; the API does not create OUs automatically. Follow with a group membership POST if group assignment is required.

Offboard (suspend then delete): PATCH {"suspended": true} to revoke access immediately while preserving data and the license seat. Use the Data Transfer API before deletion if Drive or Calendar data must be retained. DELETE the account when ready; a 20-day recovery window applies, after which deletion is permanent. Suspended users continue consuming a license until the account is deleted.

SCIM sync from an external IdP: Requires Cloud Identity Premium and a configured SSO integration as prerequisites. Generate the SCIM endpoint URL and bearer token from the Admin console, then configure the IdP (Okta, Entra ID) with those credentials. The bearer token does not expire on a fixed schedule but must be rotated periodically - regenerating it in the Admin console immediately invalidates the previous token, breaking provisioning until the IdP configuration is updated.

Provision a new employee and assign to an OU

1. Authenticate using a service account with domain-wide delegation and scope https://www.googleapis.com/auth/admin.directory.user.
2. POST to /admin/directory/v1/users with primaryEmail, name.givenName, name.familyName, password, and orgUnitPath set to the target OU (e.g., '/Engineering').
3. Store the returned immutable 'id' field as the stable reference for future updates.
4. Optionally POST to /admin/directory/v1/groups/{groupKey}/members to add the user to relevant groups.

Watch out for: If orgUnitPath is omitted, the user lands in the root OU. OU must already exist; the API does not create OUs automatically.

Offboard a user (suspend then delete)

1. PATCH /admin/directory/v1/users/{userKey} with {"suspended": true} to immediately revoke access while preserving data.
2. Optionally use the Data Transfer API to transfer Drive/Calendar data to a manager before deletion.
3. After the offboarding window, DELETE /admin/directory/v1/users/{userKey} to remove the account.
4. Account enters a 20-day recovery window; use POST /admin/directory/v1/users/{userKey}/undelete within that window if needed.

Watch out for: Suspended users still consume a license. Delete the account to free the license. Deletion is irreversible after the 20-day recovery window.

Sync users from an external IdP via SCIM

1. Ensure Cloud Identity Premium is active and SSO is configured for the target IdP (Okta or Entra ID).
2. In the Google Admin console, navigate to Security > Authentication > SSO with third-party IdP and enable SCIM provisioning.
3. Copy the generated SCIM endpoint URL and bearer token from the Admin console.
4. In the IdP (e.g., Okta), configure the Google Cloud Identity SCIM app with the endpoint URL and bearer token.
5. Map IdP user attributes to Google directory attributes (e.g., userName → primaryEmail, givenName, familyName).
6. Enable provisioning in the IdP and run an initial sync; monitor for errors in both the IdP provisioning logs and Google Admin audit logs.

Watch out for: SCIM bearer tokens generated by Google Admin console do not expire on a fixed schedule but should be rotated periodically. Regenerating the token in Admin console immediately invalidates the old token, breaking provisioning until the IdP is updated.

The Directory API manages directory identity (who exists, group membership, OU placement) but does not manage Google Cloud IAM bindings (what resources a user can access).

An integration that only calls the Directory API will leave IAM policy bindings orphaned on deletion and will not grant or revoke project-level access on provisioning - those operations require separate calls to the Cloud Resource Manager and IAM APIs.

Teams building an identity graph across Google Cloud must account for both layers: directory state via the Directory API and authorization state via the IAM API, with the resource hierarchy (Organization → Folder → Project → Resource) determining where bindings are inherited.

Stitchflow's MCP server with 60+ deep IT/identity integrations handles this cross-API identity graph reconciliation, including IAM binding cleanup on offboarding, without requiring custom orchestration between the two API surfaces.