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

> Discover the OAuth scopes gogcli uses for Gmail access. Learn about full access scopes like gmail.modify and restricted gmail.readonly mode for your security.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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:

```go
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:

```go
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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.