Sign inGet started
Docs
Get started

Google Workspace Admin API Authentication

How to authenticate Google Workspace Admin API requests: one Bearer API key plus a connectionId. MindCloud handles this app's custom auth scheme for you.

Every Google Workspace Admin API request through MindCloud needs two things: a MindCloud API Key and a connectionId for your Google Workspace Admin account. This page covers both, plus exactly how to send them, so you do not need to visit any other page to get authenticated.

Steps to authenticate

  1. Create a MindCloud account at app.mindcloud.co if you do not already have one.
  2. Generate a MindCloud API Key in API Keys. This is the Bearer token you send on every request. Keep it on your server.
  3. Create a Google Workspace Admin connection in Connections. Google Workspace Admin uses its own authentication scheme. You provide whatever it requires when you create the connection — MindCloud handles the provider-specific details for you.
  4. Copy the connection’s connectionId — you will send it on every request alongside your MindCloud API Key.

How requests are authenticated

Authentication has two layers. Your MindCloud API Key authenticates the request to MindCloud, sent as a Bearer token in the Authorization header. The connectionId selects the connected Google Workspace Admin account that should run the action. MindCloud stores and refreshes the Google Workspace Admin credentials behind that connection, so you never send provider tokens with your requests.

Pass connectionId in the query string for GET and DELETE actions, and in the JSON body for POST, PUT, and PATCH actions.

For example, calling List Users with an Google Workspace Admin connection looks like this:

curl --request GET \
  --url "https://connect.mindcloud.co/v1/universal/googleWorkspaceAdmin/latest/actions/list-users" \
  --header "Authorization: Bearer $MINDCLOUD_API_KEY" \
  --get \
  --data-urlencode "connectionId=$CONNECTION_ID"

The Authorization: Bearer <your MindCloud API Key> header authenticates you to MindCloud; the connectionId tells MindCloud which Google Workspace Admin account to run the action against. Missing or invalid Authorization returns 401, and a missing or mismatched connectionId returns 400.

Connect Google Workspace Admin with Domain-Wide Delegation

You need a Google Workspace super admin, a Google Cloud project, the Admin SDK API enabled, a service account with Domain-Wide Delegation enabled, and a secure way to store the downloaded JSON key. MindCloud will impersonate the admin email you provide when calling the Directory API.

  1. Create or choose a service account

    Open the Google Cloud project that will own this integration, then create a new service account for MindCloud or choose an existing one.

    Google Cloud console → IAM & Admin → Service Accounts
  2. Enable Domain-Wide Delegation on the service account

    Open the service account details and enable Google Workspace Domain-Wide Delegation. Copy the numeric OAuth Client ID shown for the service account. You will need that value in the Admin console and in MindCloud.

  3. Create a JSON key

    Open the Keys tab for the service account, create a new JSON key, and download the key file securely. You will copy values from this file into MindCloud.

  4. Authorize the service account in Google Admin console

    Sign in as a Google Workspace super admin. Open Security > Access and data control > API controls > Manage Domain Wide Delegation, add the service account OAuth Client ID, and authorize exactly these scopes: https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.orgunit.

    Google Admin console → Security → Access and data control → API controls → Manage Domain Wide Delegation
  5. Choose the impersonated admin user carefully

    Decide which admin email MindCloud should impersonate. This should be a super admin or a delegated admin that already has the user, group, and organizational unit privileges your workflows require.

  6. Copy the required values into MindCloud

    From the JSON key, copy client_id into Service Account Client ID, client_email into Client Email, private_key_id into Private Key ID, and private_key into Private Key. Then enter the email address of the admin user that should be impersonated into Delegated Admin Email.

  7. Test the connection with a safe read action first

    Before running any write actions, test the connection with a safe read-only workflow step such as List Users or Get User to confirm delegation and impersonation are configured correctly.

Keep your key safe

Keep your MindCloud API Key on your server; do not ship it in browser code, mobile apps, public repositories, or logs. Anyone with the key can call the Universal API as your MindCloud account, across every connection you have created.