> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Admin

> Connect Parable to Google Workspace using Service Account

export const platform_1 = "Google Workspace"

export const limit_0 = "varies by API; typically 1,500-2,400 queries/minute with per-user quotas"

export const platform_0 = "Google Workspace"

export const role_0 = "Google Workspace Super Admin"

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential              | What it is                                                                                  |
      | ----------------------- | ------------------------------------------------------------------------------------------- |
      | **Service Account Key** | JSON key file from Google Cloud — you'll enter individual fields from this file (see below) |
      | **Admin Email**         | Google Workspace super admin email for impersonation                                        |
      | **Domain**              | Your Google Workspace domain (e.g., `example.com`)                                          |
    </Card>

    <Info>
      The configuration form asks for individual fields from the service account JSON key file.
      Open the downloaded JSON file and copy each value into the corresponding form field:
      `type`, `project_id`, `private_key_id`, `private_key`, `client_email`, `client_id`,
      `auth_uri`, `token_uri`, `auth_provider_x509_cert_url`, `client_x509_cert_url`, and `universe_domain`.
    </Info>

    ## Overview

    Connect Parable to Google Workspace for directory, Gmail, Calendar, Drive, Meet, and audit data using the Admin SDK and related APIs.

    <CardGroup cols={2}>
      <Card title="Directory" icon="address-book">
        Users, groups, organizational units
      </Card>

      <Card title="Audit & Reports" icon="file-lines">
        Admin audit logs, usage reports, login activity
      </Card>
    </CardGroup>

    <Info>
      Parable reads **Google Workspace** data (directory, Gmail, Calendar, Drive, Meet, and related APIs). You still use **Google Cloud Console** to create the service account, enable APIs, and download the JSON key — that split is normal for Workspace integrations.
    </Info>

    ## Prerequisites

    <Info>
      **Setup access in {platform_0}.** These steps require **{role_0}**, or a colleague with equivalent permissions who can create credentials for you.

      If that is not you, ask your {platform_0} administrator.
    </Info>

    * **Google Cloud Console:** Create or select a GCP project, enable APIs, and create a service account — typically **Project Owner** or **Project Editor** on that project.
    * If your company uses a **Google Cloud organization** with policies that block new projects or service accounts, ask your **Google Cloud organization administrator** to complete or approve those steps.

    ## Setup Guide

    <Steps>
      <Step title="Create Google Cloud Project">
        1. Go to <a href="https://console.cloud.google.com/" target="_blank" rel="noopener noreferrer">Google Cloud Console</a>
        2. Click **Select a project** → **New Project**
        3. Name it: `Parable Integration`
        4. Click **Create**
      </Step>

      <Step title="Enable Required APIs">
        1. Go to **APIs & Services** → **Library**
        2. Search for and enable each:

        | API                       | Purpose                                                        |
        | ------------------------- | -------------------------------------------------------------- |
        | Admin SDK API             | Directory, users, groups, org units                            |
        | Gmail API                 | Email thread and message metadata                              |
        | Google Calendar API       | Calendar events                                                |
        | Google Drive API          | Drive file index, Docs, Sheets content                         |
        | Google Drive Activity API | Drive activity feed                                            |
        | Google Meet REST API      | Meet conference records, participants, transcripts, recordings |
        | Google Docs API           | Google Doc content                                             |
        | Google Sheets API         | Google Sheet content                                           |
      </Step>

      <Step title="Create Service Account">
        1. Go to **IAM & Admin** → **Service Accounts**
        2. Click **Create Service Account**
        3. Name: `parable-workspace-<your-domain>` (for example, `parable-workspace-example-com`)
        4. Click **Create and Continue**
        5. Skip role assignment → **Done**

        <Tip>
          If you connect multiple Google Workspace domains, create one service account per domain.
          Domain-specific names make future key rotation and audit review simpler.
        </Tip>
      </Step>

      <Step title="Generate Service Account Key">
        1. Click on the newly created service account
        2. Go to **Keys** tab → **Add Key** → **Create new key**
        3. Select **JSON** format
        4. Click **Create** — key file downloads automatically

        <Warning>
          Store the JSON key file securely. It cannot be downloaded again!
        </Warning>

        Rotate this key on your normal credential rotation cadence. Most teams rotate service
        account keys every 90 days or whenever an administrator with access leaves the company.
        After rotation, update the Parable connector with the new JSON key fields before deleting
        the old key in Google Cloud.
      </Step>

      <Step title="Enable Domain-Wide Delegation and Note Client ID">
        1. On the service account details page, go to the **Details** tab
        2. Expand **Advanced settings**
        3. Check **Enable Google Workspace Domain-wide Delegation** and click **Save**
        4. The **Client ID** (numeric, \~21 digits) will now appear in that section — copy it for the next step

        <Info>
          The Client ID is also available as the `client_id` field in the downloaded JSON key file.
        </Info>
      </Step>

      <Step title="Configure Domain-Wide Delegation">
        1. Open <a href="https://admin.google.com" target="_blank" rel="noopener noreferrer">Google Admin Console</a>
        2. Go to **Security** → **Access and data control** → **API controls**
        3. Click **Manage Domain Wide Delegation**
        4. Click **Add new**
        5. Enter:

        | Field        | Value                                 |
        | ------------ | ------------------------------------- |
        | Client ID    | Service account Client ID from Step 5 |
        | OAuth Scopes | See scope list below                  |
      </Step>

      <Step title="Add Required Scopes">
        Add these scopes as a comma-separated list. The exact set depends on which Google data
        categories you enable in Parable.

        | Data category         | OAuth scope                                                        |
        | --------------------- | ------------------------------------------------------------------ |
        | Directory users       | `https://www.googleapis.com/auth/admin.directory.user.readonly`    |
        | Directory groups      | `https://www.googleapis.com/auth/admin.directory.group.readonly`   |
        | Organizational units  | `https://www.googleapis.com/auth/admin.directory.orgunit.readonly` |
        | Gmail metadata        | `https://www.googleapis.com/auth/gmail.readonly`                   |
        | Calendar events       | `https://www.googleapis.com/auth/calendar.readonly`                |
        | Drive files           | `https://www.googleapis.com/auth/drive.readonly`                   |
        | Drive activity        | `https://www.googleapis.com/auth/drive.activity.readonly`          |
        | Meet records          | `https://www.googleapis.com/auth/meetings.space.readonly`          |
        | Chrome audit activity | `https://www.googleapis.com/auth/admin.reports.audit.readonly`     |

        The optional **chrome\_activity** tap ingests all Chrome application audit events from the
        Admin Reports API (login, device, DLP, Safe Browsing, content transfer, and related event
        types). It is **not enabled by default** — turn it on in your connector configuration when
        you need Chrome browser or ChromeOS activity in Parable. The first sync can backfill up to
        **90 days** of history (in 7-day API windows).

        <Info>
          Parable no longer requires deprecated per-resource Google Meet scopes. Use
          `https://www.googleapis.com/auth/meetings.space.readonly` for Meet data.
        </Info>

        Click **Authorize**
      </Step>

      <Step title="Enter values in the form">
        Enter the values from your service account JSON key, plus **Admin email** and **Domain**, into the connector form, then click **Save & test connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    Use a Google API client library or OAuth Playground to test:

    <CodeGroup>
      ```python Python Example theme={null}
      from google.oauth2 import service_account
      from googleapiclient.discovery import build

      SCOPES = ['https://www.googleapis.com/auth/admin.directory.user.readonly']
      SERVICE_ACCOUNT_FILE = 'path/to/service-account-key.json'
      ADMIN_EMAIL = 'admin@yourcompany.com'

      credentials = service_account.Credentials.from_service_account_file(
          SERVICE_ACCOUNT_FILE, scopes=SCOPES)
      delegated_credentials = credentials.with_subject(ADMIN_EMAIL)

      service = build('admin', 'directory_v1', credentials=delegated_credentials)
      results = service.users().list(customer='my_customer', maxResults=5).execute()
      print(results.get('users', []))
      ```
    </CodeGroup>

    <Check>
      **Success!** If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    <Tip>
      Enter the service account JSON fields, **Admin email**, and **Domain** in the connector form, then click **Save & test connection**.
    </Tip>

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error                                            | Meaning            | Solution                         |
    | ------------------------------------------------ | ------------------ | -------------------------------- |
    | `403 Not Authorized to access this resource/api` | Missing delegation | Configure domain-wide delegation |
    | `400 Invalid Input`                              | Wrong admin email  | Use a valid super admin email    |
    | `401 Invalid Credentials`                        | Bad key or expired | Regenerate service account key   |
    | `429 Rate Limit Exceeded`                        | Too many requests  | Implement exponential backoff    |

    <Accordion title="Common Issues">
      ### "Domain-wide delegation not configured"

      Ensure the Client ID (numeric) is added to Domain-wide Delegation in Admin Console, not the service account email.

      ### "User not found" when impersonating

      The admin email used for impersonation must be a valid super admin in the Google Workspace domain.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Admin SDK" icon="book" href="https://developers.google.com/admin-sdk">
        Google Admin SDK documentation
      </Card>

      <Card title="Domain-Wide Delegation" icon="key" href="https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority">
        Delegation setup guide
      </Card>
    </CardGroup>
  </Tab>
</Tabs>