Valkan Integration Guides
Valkan Site Valkan App

Connect with Google Workspace

Create the service account Valkan uses to read your Workspace directory, OAuth grants and audit logs, then connect.

Complete these steps before choosing Connect Google Workspace in Valkan. Valkan reads your user directory, the OAuth grants your employees have made to third-party apps, and admin, token and Drive audit logs.

Two roles take part, often two people:

  • a Google Cloud project admin for steps 1–3 (creating the service account and its key)
  • a Google Workspace super admin for step 4 (domain-wide delegation)

Valkan only reads. It lists users, OAuth grants and audit events; it never creates, changes or deletes anything in your Workspace. One scope, admin.directory.user.security, is broader than that: it is the only scope Google offers for listing OAuth grants, and it would also allow revoking them. Valkan uses it only to list grants.

1. Create the service account

  1. Go to console.cloud.google.com/iam-admin/serviceaccounts.
  2. Click Create Service Account, name it (e.g. valkan-workspace), and click Create and Continue → Done. It needs no Google Cloud project roles.
  3. Open the service account and copy its Client ID — a long numeric string, not the JSON key. You'll need it in step 4.

2. Create a key

  1. On the service account, go to the Keys tab → Add Key → Create new key → JSON → Create.
  2. A file downloads — you'll paste its contents into Valkan in the last step.

Organizations created on or after 3 May 2024 block service account keys by default (the iam.disableServiceAccountKeyCreation policy). If Add Key is refused, ask an organization policy administrator to allow key creation for this project.

3. Enable the Admin SDK API

Go to console.cloud.google.com/apis/library/admin.googleapis.com in the project that owns the service account, and click Enable. It covers both the directory and the audit-log (Reports) calls; without it, every call fails with a 403 even when the scopes are correct.

4. Grant domain-wide delegation

A Workspace super admin does this step.

  1. Go to admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new.
  2. Paste the Client ID from step 1.
  3. Add these 5 scopes, comma-separated:
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.customer.readonly,
https://www.googleapis.com/auth/admin.directory.domain.readonly,
https://www.googleapis.com/auth/admin.directory.user.security

Then click Authorize. If your organization requires multi-party approval, a second super admin must approve the change.

Add all five: Valkan requests them together, and Google refuses the whole request if any one is missing from the delegation.

5. Connect in Valkan

  1. In Valkan, choose Integrations → Sources → Connect → Google Workspace.
  2. Paste the JSON key's contents.
  3. Enter the email of the admin Valkan will act as, and click Connect.

Use a super admin. A delegated admin with the Users → Read, Reports and User Security Management privileges may also work, but has not been verified.

Limits

  • Drive audit events are available only on Google Workspace Business and Enterprise editions, and mostly for files owned by users on those editions.
  • Admin role assignments are not read today: listing them needs a role-management scope that Valkan does not yet request.