Google Workspace Collection

Google Workspace Collection Integration with Onna

Overview

This guide explains how to set up and interact with a Google Workspace collection through the Onna Platform API. Unlike most other connectors, Google Workspace does not use an OAuth2 redirect flow. It authenticates with a Google service account certificate that has domain-wide delegation. You'll learn how to create a workspace and collection, register the service account credentials in a wallet, list the users, team drives, and per-user folders available in the domain, configure sync filters to control exactly what is synchronized, start the sync, and clean up your environment afterward.

Before you start, you'll need:

• A Google Workspace domain (for example company.com).
• Admin access to that domain.
• A Google service account certificate (JSON key file) with domain-wide delegation configured for the Google Workspace APIs Onna needs to access.

Create a workspace

A workspace is the main container for your project in Onna. Create one with a POST request.

curl --location --request POST 'https://api.onna.com/v1/workspaces' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My New Workspace",
  "description": "This is a workspace for organizing Google Workspace data in Onna."
}'

Where:

• name is the name of the workspace.
• description is a brief description of the workspace's purpose.

A successful response (201) will return:

{
  "onna_id": "<WORKSPACE_ID>"
}

Create a Google Workspace Wallet

Google Workspace credentials are stored in a wallet as a base64-encoded service account certificate, along with the admin email and domain the certificate is scoped to.

curl --location --request POST 'https://api.onna.com/v1/wallet' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Google Workspace",
  "credentials": "<BASE64_ENCODED_SERVICE_ACCOUNT_JSON>",
  "metadata": {
    "admin_mail": "admin@company.com",
    "domain": "company.com"
  },
  "credential_type_name": "GSuiteEDatasource",
  "credentials_scopes_type": "preservation"
}'

Where:

• name is a label for the wallet.
• credentials is your service account certificate JSON, base64-encoded.
• metadata.admin_mail is the email of a Google Workspace admin the service account impersonates.
• metadata.domain is your Google Workspace domain.
• credential_type_name must be GSuiteEDatasource for Google Workspace.
• credentials_scopes_type is preservation for a full collection, or content.read for read-only access.

A successful response (201) will return:

{
  "onna_id": "<WALLET_ID>"
}

Create a Google Workspace Collection

Create the collection, then configure it with the data types, datasource types, and sync behavior you want.

curl --location --request POST 'https://api.onna.com/v1/collections' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Google Workspace Collection",
  "onna_parent_id": "<WORKSPACE_ID>",
  "type": "gsuite",
  "wallet_credentials": "<WALLET_ID>"
}'

Where:

• name is the name of the collection.
• onna_parent_id is the ID of the workspace that this collection will belong to.
• type is the type of collection being created. For Google Workspace, the type is gsuite.
• wallet_credentials is the ID of the wallet you created for the Google Workspace service account.

A successful response (201) will return:

{
  "onna_id": "<COLLECTION_ID>",
  "type": "gsuite"
}

Then configure the scope of what will be synced with a PATCH request:

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "data_types": ["resources", "preservation"],
  "datasource_types": ["GMailDatasource", "GDriveEDatasource", "GVaultDatasource"],
  "type_sync": "arch",
  "skip_spam_and_trash": true,
  "username": "admin@company.com"
}'

Where:

• data_types are the data categories to sync (for example resources, preservation).
• datasource_types are the Google Workspace products to include. Allowed values: GMailDatasource, GDriveEDatasource, GVaultDatasource.
• type_sync is the sync type: one, arch, or auto.
• skip_spam_and_trash skips Gmail's spam and trash folders when set to true.
• username is the email used for Google Workspace collections, typically the admin email.

Actionable Tips: While creating collections, consider adding metadata that might be required later for reporting or analysis.

You might also want to implement a naming convention (like Collection-{WorkspaceName}-GSuite) for better organization.

Retrieve the List of Users

To retrieve the users available in the Google Workspace domain, send a GET request to the collection's /users endpoint.

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/users' \
--header 'Authorization: Bearer <token>'

Example response:

{
  "results": [
    { "name": "Lisa Simpson", "email": "lisa@company.com", "suspended": false },
    { "name": "Bart Simpson", "email": "bart@company.com", "suspended": false }
  ],
  "nextPageToken": null
}

Where:

• email is the user's email address. Use this value to select users in sync_filters, and as the user_id when listing that user's folders below.
• nextPageToken is the token for the next page of results, or null when there are no more pages.

Retrieve Team Drives

Team drives are shared across the domain rather than owned by a single user.

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/team-drives?limit=100' \
--header 'Authorization: Bearer <token>'

Example response:

{
  "team_drives": [
    { "id": "0AIl4c5cO9nfoUk9PVA", "name": "Marketing Team Drive" }
  ],
  "next_cursor": null
}

• limit is the page size (1-100, defaults to 100).
• offset is the cursor from a previous response's next_cursor. Omit it for the first page.
• next_cursor is null on the last page.

To list the first-level folders inside a specific team drive, use its id as a path parameter:

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/team-drives/<TEAM_DRIVE_ID>' \
--header 'Authorization: Bearer <token>'

{
  "children": [
    { "id": "1a2b3c4d5e6f", "name": "Q4 Campaigns" }
  ]
}

Retrieve Folders and Shared Folders

A Google Workspace user has two independent folder lists: My Drive (folders the user owns), and the folders other people have shared with the user, labeled Shared with me in Google's own UI. These are two separate endpoints, each paginated independently: a request to one has no effect on the other's position.

My Drive folders:

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/folders?user_id=lisa@company.com&limit=50' \
--header 'Authorization: Bearer <token>'

The other list (Google's Shared with me):

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/shared-folders?user_id=lisa@company.com&limit=50' \
--header 'Authorization: Bearer <token>'

Both return the same shape:

{
  "folders": [
    { "id": "1FAcp1oqW", "name": "Modern Attachments" }
  ],
  "next_cursor": null
}

Where:

• user_id is the email of the user whose folders you're listing. Required for both endpoints.
• limit is the page size (defaults to 100).
• offset is the cursor from a previous response's next_cursor. Omit it for the first page.
• next_cursor is null on the last page.

Configure Sync Filters

Sync filters control what is synchronized. For Google Workspace, the sync_filters object can contain up to four kinds of keys:

• users: which domain users to sync.
• team_drives: which team drives to sync.
• vault: whether to include deleted content, and which Google products to cover.
• One entry per user email you want to scope individually, each containing that user's folders and shared_folders selection (from the two endpoints above).

Update the collection with the selected configuration by sending a PATCH request:

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "sync_filters": {
    "users": {
      "filter_type": "users",
      "all_selected": false,
      "selected": [{ "id": "lisa@company.com" }],
      "excluded": []
    },
    "team_drives": {
      "filter_type": "team_drives",
      "all_selected": true,
      "selected": [],
      "excluded": [{ "id": "0AIl4c5cO9nfoUk9PVA", "recursive": false }]
    },
    "vault": {
      "filter_type": "vault",
      "include_deleted_content": true,
      "products": ["GMailDatasource", "GDriveEDatasource"],
      "all_selected": true,
      "selected": [],
      "excluded": []
    },
    "lisa@company.com": {
      "folders": {
        "filter_type": "folders",
        "all_selected": false,
        "selected": [],
        "excluded": [{ "id": "1FAcp1oqW" }]
      },
      "shared_folders": {
        "filter_type": "shared_folders",
        "all_selected": true,
        "selected": [],
        "excluded": []
      }
    }
  }
}'

Filter fields

users and team_drives share the same shape:

Field	Type	Description
filter_type	String	"users" or "team_drives", matching the key.
all_selected	Boolean	If true, every entry is synchronized (use excluded to carve out exceptions). When false, only selected entries are included.
selected	Array	Entries to include when all_selected is false. Each entry is { "id": "<value>" }: the user's email for users, the team drive's id for team_drives.
excluded	Array	Entries to exclude when all_selected is true. Team drive entries may also set "recursive": false.

vault controls Vault-specific behavior:

Field	Type	Description
filter_type	String	Always "vault".
include_deleted_content	Boolean	Whether to include content Vault has retained after deletion.
products	Array	Google products Vault should cover, for example ["GMailDatasource", "GDriveEDatasource"].
all_selected / selected / excluded	N/A	Same meaning as above.

A per-user email key (only needed for users whose folders you want to scope individually) contains folders and shared_folders, each with the same filter_type / all_selected / selected / excluded shape as users/team_drives above, with filter_type set to "folders" or "shared_folders" respectively and entries from the /folders and /shared-folders endpoints.

All keys are optional. Include only the ones you want to scope; omitting a key does not mean

"sync nothing" for it. It means the collection's existing configuration for that key is left as-is on update, or defaults apply on creation.

A successful PATCH returns 204 No Content, indicating the filter configuration was saved.

Update Existing Filters

To change an existing filter configuration (for example, to add or remove users, team drives, or a user's folder selection), issue another PATCH to the same collection endpoint with the updated sync_filters object.

Send only the keys you want to change. Unlike some other connectors, omitted sync_filters keys are

not treated as cleared. Send the full object only if you intend to replace every key at once.

Start the Sync

Once the filters are saved, initiate the sync process.

curl --location --request POST 'https://api.onna.com/v1/collections/<COLLECTION_ID>/start' \
--header 'Authorization: Bearer <token>'

A successful response (HTTP status code 200) indicates that the sync process has begun. Only the users, team drives, folders, and Vault scope allowed by the configured filters are pulled into the collection.

Clean Up

Once you are done, you can clean up by deleting both the collection and the workspace.

curl --location --request DELETE 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>'

curl --location --request DELETE 'https://api.onna.com/v1/workspaces/<WORKSPACE_ID>' \
--header 'Authorization: Bearer <token>'

Note: Deleting a collection or workspace is permanent and cannot be undone.