What OAuth Scopes Does gogcli Use for Gmail? A Complete Guide

gogcli requests three default OAuth scopes for full Gmail access (gmail.modify, gmail.settings.basic, gmail.settings.sharing) and switches to a single restrictive gmail.readonly scope when read-only mode is enabled.

Understanding which OAuth scopes gogcli uses for Gmail is essential for security auditing and permission management. The steipete/gogcli repository implements a flexible scope selection system that adapts based on operational requirements. This guide breaks down the exact permissions requested, where they are defined in the source code, and how to configure read-only access.

Default Gmail OAuth Scopes in gogcli

When operating in standard mode, gogcli requests comprehensive access to Gmail functionality through three distinct OAuth scopes. These are defined in the serviceInfoByService map within internal/googleauth/service.go at lines 80-85.

The default scopes include:

• https://www.googleapis.com/auth/gmail.modify — Grants permission to read, compose, send, and delete messages, plus modify message labels
• https://www.googleapis.com/auth/gmail.settings.basic — Allows reading and updating basic Gmail settings such as signatures and vacation responders
• https://www.googleapis.com/auth/gmail.settings.sharing — Enables management of Gmail delegation and sharing settings

These permissions allow gogcli to perform full email management operations, including sending mail, organizing messages through labels, and configuring account settings programmatically.

Read-Only Mode Scope Restrictions

For scenarios requiring minimal permissions, gogcli supports a read-only configuration that restricts access to a single, narrowly defined scope. When the Readonly option is set to true, the application replaces the default three-scope set with:

• https://www.googleapis.com/auth/gmail.readonly — Permits only reading messages, threads, and labels without modification rights

This substitution logic is implemented in the scopesForServiceWithOptions function at lines 18-24 of internal/googleauth/service.go. The function checks the opts.Readonly boolean for ServiceGmail and returns the restricted scope array when enabled.

How gogcli Implements Scope Selection

The scope resolution process relies on two primary functions exported by the googleauth package. The implementation uses the ServiceGmail constant to identify the Gmail service during scope resolution.

Standard Scope Retrieval

To obtain the default Gmail scopes programmatically:

package main

import (
    "strings"
    "github.com/steipete/gogcli/internal/googleauth"
    "golang.org/x/oauth2"
)

func main() {
    // Retrieve default Gmail scopes
    scopes, err := googleauth.Scopes(googleauth.ServiceGmail)
    if err != nil {
        panic(err)
    }
    
    // scopes contains:
    // ["https://www.googleapis.com/auth/gmail.modify",
    //  "https://www.googleapis.com/auth/gmail.settings.basic",
    //  "https://www.googleapis.com/auth/gmail.settings.sharing"]
    
    // Use in OAuth2 config
    authURL := oauth2Config.AuthCodeURL(state,
        oauth2.AccessTypeOffline,
        oauth2.SetAuthURLParam("scope", strings.Join(scopes, " ")),
    )
}

Read-Only Scope Configuration

To request read-only access:

package main

import (
    "github.com/steipete/gogcli/internal/googleauth"
)

func main() {
    // Configure read-only options
    opts := googleauth.ScopeOptions{
        Readonly: true,
    }
    
    // Get read-only scopes for Gmail
    scopes, err := googleauth.ScopesForManageWithOptions(
        []googleauth.Service{googleauth.ServiceGmail},
        opts,
    )
    if err != nil {
        panic(err)
    }
    
    // scopes now contains:
    // ["https://www.googleapis.com/auth/gmail.readonly", "openid", "email", ...]
}

The ScopesForManageWithOptions function aggregates scopes across multiple services while applying the read-only restriction to Gmail specifically.

Summary

• gogcli uses three default OAuth scopes for Gmail: gmail.modify, gmail.settings.basic, and gmail.settings.sharing
• Read-only mode restricts permissions to a single gmail.readonly scope, eliminating write access
• Scope definitions reside in internal/googleauth/service.go within the serviceInfoByService map and scopesForServiceWithOptions function
• Implementation uses the ServiceGmail constant and ScopeOptions struct to toggle between full and restricted access modes

Frequently Asked Questions

What are the exact OAuth scopes gogcli requests for Gmail?

In standard operation, gogcli requests https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.settings.basic, and https://www.googleapis.com/auth/gmail.settings.sharing. These permissions enable reading, composing, sending, and deleting messages, plus managing labels and account settings. When read-only mode is activated, only https://www.googleapis.com/auth/gmail.readonly is requested.

How do I enable read-only mode in gogcli to restrict Gmail permissions?

Set the Readonly field to true in the ScopeOptions struct when calling ScopesForManageWithOptions. Pass googleauth.ServiceGmail as the target service. This triggers the logic in internal/googleauth/service.go that substitutes the default three-scope array with the single gmail.readonly scope.

Where are the Gmail OAuth scopes defined in the gogcli source code?

The scopes are defined in internal/googleauth/service.go. The default set appears in the serviceInfoByService map at lines 80-85, associated with the ServiceGmail key. The read-only substitution logic is implemented in the scopesForServiceWithOptions function at lines 18-24, which checks the opts.Readonly boolean before returning scope values.

Why does gogcli need Gmail settings scopes?

The gmail.settings.basic and gmail.settings.sharing scopes enable programmatic management of account configurations beyond simple email operations. This includes updating signatures, configuring vacation responders, and managing delegation settings. These permissions support advanced automation workflows where gogcli may need to modify account behavior, not just read or send messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}