Connect Google Workspace

What you will configure

1. Google Cloud project
2. OAuth client
3. Consent
4. Encrypted Agent Secret
5. gog runtime

Google Cloud project
        │
        ├── Enable selected APIs
        ├── Configure OAuth consent
        └── Create Web application client
                    │
                    ▼
            Agent Barn OAuth flow
                    │
                    ├── Select services
                    ├── Select access level
                    └── Grant consent
                              │
                              ▼
                    Encrypted Agent Secret
                              │
                              ▼
                    Agent start or restart
                              │
                              ▼
                         gog CLI

Google Workspace uses the gog CLI. It is separate from aai-cli, and does not use an aai-cli profile.

Before you begin

You need:

• A Google account that can create or use a Google Cloud project
• Permission to configure the project’s OAuth consent screen
• Permission to create OAuth credentials
• Access to the Google Workspace account the Agent will use
• Access to configure the Agent
• agent.update and agent.secret.manage permissions
• Lifecycle permission when connecting a running Agent
• Popups allowed for the Agent Barn site

Decide which Google services the Agent needs before creating the connection.

Supported services

One credential can cover any combination of Gmail, Calendar, Drive, and Sheets. The selected services are stored with the credential, and reconstructed in the gog runtime when the Agent starts.

Choose an access level

Agent Barn supports one access level across all services selected in a connection: Read-only or Full access.

Read-only requests view-only scopes. Google enforces the restriction even if the Agent attempts a write operation.

Understand the requested scopes

Agent Barn derives scopes from the selected services and access level. Identity scopes are always requested, so the connected account can be identified:

openid
email
https://www.googleapis.com/auth/userinfo.email

Sheets includes Drive access because gog uses Drive for spreadsheet discovery and export operations. When several services are selected, Agent Barn combines and deduplicates their scopes.

How the OAuth flow is protected

1. Signed state token Records the google_workspace provider and expires after ten minutes
2. Google redirects the popup Returns an authorization code and the signed state
3. Callback validates the state The short-lived code is handed to the same-origin opener
4. Authenticated token exchange The web application exchanges the code for tokens
5. Encrypted Agent Secret Saved through the normal credential flow

The callback does not expose the client secret or refresh token.

What Agent Barn stores

The Google Workspace credential contains the connected account email, the selected services, the scopes Google granted, the refresh token, the read-only setting, the OAuth client ID, and the OAuth client secret.

The complete payload is encrypted as an Agent Secret. Read APIs return only credential metadata — they do not return the refresh token or client secret.

Runtime behavior

Google Workspace is materialized when the Agent starts. Agent Barn:

1. Decrypts the stored Google Workspace credential.
2. Creates the gog client configuration.
3. Imports the refresh token.
4. Generates a new keyring password.
5. Adds Google Workspace guidance to the Agent’s AGENTS.md context.
6. Starts the Agent with the selected services available.

Encrypted Agent Secret
        │
        ▼
Agent start
        │
        ▼
Fresh ephemeral GOG_HOME
        │
        ▼
Authenticated gog CLI

The runtime state is stored in an ephemeral GOG_HOME, separate from the Agent’s persistent workspace. Agent Barn wipes and rebuilds GOG_HOME on every start, and the encrypted Agent Secret remains the source of truth.

Removing the credential removes runtime access on the next restart.

gog is separate from aai-cli

Google Workspace uses gog, not aai-cli. The Agent should not:

• Pass an aai-cli --profile
• Ask the user to authenticate again
• Request a token in conversation
• Use browser automation as a fallback
• Invent message, file, spreadsheet, or event IDs

The runtime supplies the account and credential automatically. The Agent can discover commands using:

gog <service> --help

Change the enabled services

To add or remove services:

1. Open the Google Workspace integration.
2. Select the desired service set.
3. Choose the access level.
4. Authenticate with Google again.
5. Grant the requested scopes.
6. Apply the replacement credential.
7. Restart the Agent.
8. Validate the connection.
9. Test each selected service.

Editing the stored service list without reconnecting is not sufficient. The refresh token must cover the new scope set.

Change from read-only to Full access

1. Confirm that the Agent’s workflow requires write access.
2. Review the impact with the Google Workspace administrator.
3. Change the access level to Full access.
4. Reconnect with Google.
5. Review the expanded scopes carefully.
6. Apply and restart.
7. Validate.
8. Test a reversible write against non-production data.

To reduce access, reconnect with Read-only, and consider revoking the previous grant from the Google account’s connected-app settings.

Switch Google accounts

1. Begin a new Google Workspace authentication.
2. Select the intended Google account in the OAuth window.
3. Confirm the connected email in Agent Barn.
4. Apply the replacement credential.
5. Restart the Agent.
6. Validate the identity.
7. Revoke the old account’s grant if it is no longer required.

Agent Barn validation reports an error if the refreshed credential authenticates as a different account than the stored email.

Remove Google Workspace

1. Stop the Agent, or begin a restart-aware configuration edit.
2. Open Keys & integrations.
3. Select Remove for Google Workspace.
4. Confirm that no assigned Skill requires google_workspace.
5. Apply the configuration.
6. Restart the Agent.
7. Confirm that Google Workspace is no longer available.
8. Revoke the application grant in the Google account when appropriate.

API reference

Request an authorization URL

This endpoint requires an authenticated user.

GET /api/v1/integrations/google/authorize-url

Example query:

GET /api/v1/integrations/google/authorize-url?provider=google_workspace&services=gmail,drive&read_only=true&client_id=REDACTED.apps.googleusercontent.com

{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

Supported service identifiers are:

gmail
calendar
drive
sheets

At least one service is required.

OAuth callback

GET /api/v1/integrations/google/callback

Google redirects the popup to this endpoint. Do not call it manually — it validates the signed state and returns the authorization result to the originating browser window.

Exchange the authorization code

This endpoint requires an authenticated user.

POST /api/v1/integrations/google/token
Content-Type: application/json

{
  "code": "REDACTED",
  "client_id": "REDACTED.apps.googleusercontent.com",
  "client_secret": "REDACTED"
}

{
  "refresh_token": "REDACTED",
  "granted_scopes": [
    "openid",
    "email",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/gmail.readonly"
  ],
  "email": "[email protected]"
}

Save the Agent credential

The Agent must be stopped.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

{
  "secrets": [
    {
      "provider": "google_workspace",
      "content": {
        "email": "[email protected]",
        "services": [
          "gmail",
          "drive"
        ],
        "scopes": [
          "openid",
          "email",
          "https://www.googleapis.com/auth/userinfo.email",
          "https://www.googleapis.com/auth/gmail.readonly",
          "https://www.googleapis.com/auth/drive.readonly"
        ],
        "refresh_token": "REDACTED",
        "read_only": true,
        "client_id": "REDACTED.apps.googleusercontent.com",
        "client_secret": "REDACTED"
      }
    }
  ]
}

The saved scopes must cover every selected service at the configured access level.

Validate the credential

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/google_workspace/validate

Validation requires agent.secret.manage.

Remove the credential

The Agent must be stopped.

{
  "removed_secret_providers": [
    "google_workspace"
  ]
}

Troubleshooting

Recommended practices

• Use a Google account dedicated to the Agent’s role
• Create the OAuth client in an organization-controlled project
• Use an Internal consent screen when appropriate
• Move External applications out of Testing for durable connections
• Select only the required services
• Prefer read-only access
• Enable only the necessary Google APIs
• Copy the redirect URI exactly
• Protect the downloaded client JSON
• Verify the connected account email
• Validate after connecting or rotating credentials
• Test with non-sensitive mail, calendars, files, and spreadsheets
• Restart the Agent after every credential change
• Revoke superseded grants through the Google account
• Never paste refresh tokens or client secrets into Agent conversations
• Review Google Cloud audit and OAuth usage regularly

Next steps

Continue to Connect GitHub to configure repository access with a scoped personal access token.

• Manage Agent credentials
• Work with Skills
• Review Agent health and logs