Google Workspace SDK: get started

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Install

npm install @alter-ai/sdk @alter-ai/google
# Python (installs core automatically)
pip install alter-sdk-google

The provider package includes only Google Workspace types and response schemas and pins its contract version.

Connect and call

Configure Google Workspace, request the scopes the application needs, and retain each customer’s grant ID after Connect consent. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { GoogleIntegration } from "@alter-ai/google";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const client = new GoogleIntegration(app, { grantId: process.env.GOOGLE_GRANT_ID! });
  const result = await (await client.driveFiles.driveFilesList({})).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_google import GoogleIntegration

async def first_call(api_key: str, grant_id: str):
    async with App(api_key=api_key) as app:
        client = GoogleIntegration(app, {"grant_id": grant_id})
        call = await client.drive_files.drive_files_list({})
        result = await call.wait()
        return result.body_json()

Complete versioned contract

Contract 2026-10-27 contains 180 REST operations from the official Gmail v1, Calendar v3 and Drive v3 Discovery documents, plus two Drive upload and two binary-download variants. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations google --version 2026-10-27 also expose the schemas.

Generated calls pin the Alter contract version. Google Workspace’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

alter integrations execute google google.drive_files_list \
  --version 2026-10-27 --grant "$GOOGLE_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

Approvals

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

Uploads and approvals

Gmail message and draft writes accept Google’s base64url-encoded MIME raw field. Drive drive.files.createUpload and drive.files.updateUpload accept body.metadata plus body.file containing filename, content_type, and content_base64; Alter encodes Google’s multipart/related request with uploadType=multipart. The shared 5 MiB serialized-input ceiling applies. Large resumable upload sessions are not part of this version’s upload transport.

Opaque Drive upload bytes, private signing material, conference passwords and webhook tokens cannot be retained in pending approvals. Calls requiring these values must execute under a policy that authorizes immediate dispatch. Gmail MIME messages can use the encrypted approval flow with recipient validation, as can read calls and metadata-only writes.

Policy and sensitive data

Gmail delivery, Calendar attendee notifications and Drive sharing/comment notifications carry send. Roles, permissions, forwarding settings and notification channels carry admin; destructive actions carry delete. Existing Gmail recipient and Calendar attendee/time projections remain enforced. No operation is classified as a payment. drive.files.generateCseToken is deliberately excluded because it mints an authorization token; raw calls to that route are cataloged as credential minting and refused by default unless an operator explicitly authorizes them with a credential_minting rule. Gmail MIME requests retain the existing encrypted approval flow and recipient validation. Credential material and opaque file uploads cannot be retained in pending approvals. Managed request and response body capture is disabled; audit metadata remains available. Google HTTP errors use the shared typed provider errors; there is no documented provider-wide 2xx fault envelope.

Google’s per-method scope list contains alternatives: any one documented permission is sufficient upstream. Restricted scopes such as drive.file, metadata-only scopes and calendar-owner scopes require an equally restricted provider credential when used as a delegated ceiling; Alter cannot use them to narrow a broader token safely. Request only the scopes you need. Domain-wide delegation and Workspace administrator requirements on some Gmail settings endpoints still apply; adding the SDK does not grant those privileges.

Maintenance

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Resume after a restart

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Rules for SDK functions

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations google. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
  "effect": "require_approval",
  "when": { "operation": "google.gmail_users_labels_create" },
  "approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.

Use driveFiles.driveFilesGetMedia / drive_files.drive_files_get_media or the corresponding revisions getMedia method for file bytes. These operations freeze alt=media and retain the binary decoder when an approval is resumed. The ordinary get methods return JSON metadata.