⌕

Google Drive read connector

The Google Drive connector lets an agent read one file that a user explicitly selects in Google Picker. It does not receive broad access to the user's Drive, and the OAuth token and file content stay in Axtary's local enforcement plane.

Status: live. This connector is verified end to end against real Google Drive with a drive.file-scoped OAuth client: the one file you pick reads back within its byte cap, a file you did not pick is refused — by Axtary's policy allowlist and again by Google itself (isAppAuthorized=false) — and the exported ledger verifies with no OAuth tokens or file content inside it.

What an agent can do

ActionScopeDefault treatment
drive.files.readone exact drive:file:<fileId> resourcedenied until the file id is policy-allowlisted

Axtary requests only Google's https://www.googleapis.com/auth/drive.file scope. During connection, Google Picker asks the user to choose one file and returns that file id with the OAuth callback. Axtary stores the token locally and keeps the selected id as non-secret connection metadata.

Before content is downloaded, the adapter reads the file's metadata and requires Google to report isAppAuthorized=true. An arbitrary file id that was not selected for this app fails closed.

Connect it

In Google Cloud, enable the Drive API and Picker API, then create an OAuth client. The Picker's trigger_onepick flow needs a custom HTTPS redirect, which only a Web application client can register (a Desktop client allows only localhost) — and a Web client is confidential, so it has a client secret you must supply alongside the client id. Register a tunnel URL (e.g. ngrok or cloudflared) that forwards to Axtary's local callback listener as an Authorized redirect URI, and add your Google account as a test user.

export AXTARY_DRIVE_CLIENT_ID="...apps.googleusercontent.com"
export AXTARY_DRIVE_CLIENT_SECRET="..."   # required: Web-app clients are confidential

axtary connect drive \
  --redirect-uri https://your-tunnel.example/callback \
  --redirect-port 7878

The browser request uses drive.file only, prompt=consent, and trigger_onepick=true. Select one Google Doc or supported textual file. The token is stored in the local credential broker (OS keychain when it can store and read back the secret, otherwise the 0600 file — both keep the token off the agent and out of the ledger).

Inspect non-secret connection metadata:

axtary connections --json

Copy the returned selectedFileId into the policy allowlist:

adapters:
  drive:
    mode: rest
    tokenEnv: AXTARY_DRIVE_ACCESS_TOKEN # optional env fallback
    maxReadBytes: 100000
    allowedMimeTypes:
      - application/vnd.google-apps.document
      - text/plain
      - text/markdown
      - text/html
      - text/csv
      - application/json
      - application/xml

policy:
  drive:
    reads:
      allowedFileIds:
        - YOUR_PICKED_FILE_ID
      maxReadBytes: 100000

The broker credential takes precedence over tokenEnv. The selected file id is not authority by itself: policy must independently allow the same id, and the normalized resource must be exactly drive:file:<fileId>.

Check and run

The local smoke check reads selected-file metadata only; it never downloads the file:

axtary doctor connectors --config examples/axtary.drive.yml
axtary smoke --config examples/axtary.drive.yml

Run the governed read:

axtary run workflow drive-read --real \
  --config examples/axtary.drive.yml \
  --file-id YOUR_PICKED_FILE_ID \
  --max-bytes 100000

If --file-id is omitted, Axtary uses the id captured from the most recent axtary connect drive Picker flow.

Google Docs export as bounded plain text. Supported textual blob files download through the Drive API. Unsupported MIME types or content above the configured byte cap fail closed.

What the ledger records

The authorization record contains the file id, exact resource, drive.file scope, and byte cap. The execution outcome may add the provider-returned title, MIME type, URL, isAppAuthorized state, and returned byte count.

The ledger, attestation export, hosted dashboard, and CLI diagnostics do not contain:

  • access or refresh tokens;
  • the file body;
  • authorization headers.

Use axtary attest-ledger followed by axtary verify-export to verify the result independently.

Google references