Gmail API: batchDelete returns 403 with gmail.modify scope

[ayushmanpani]

Environment details

• OS type and version: Windows 10 (64-bit)
  -Python version: Python 3.13.7
  -pip version: pip 25.2
  -google-api-python-client version: 2.xx.x

Steps to reproduce

1. Create a Google Cloud project.
2. Enable Gmail API for the project.
3. Configure OAuth consent screen:
   - User type: External
   - App status: Testing
   - Add the account owner as a test user
   - Add scope: https://www.googleapis.com/auth/gmail.modify
4. Create an OAuth 2.0 Desktop client and download credentials.json.
5. Authenticate via OAuth 2.0 using the gmail.modify scope.
6. Call users.messages.batchDelete on a valid message ID belonging to the authenticated user.

Code example

service = build("gmail", "v1", credentials=creds)

service.users().messages().batchDelete(
    userId="me",
    body={"ids": ["MESSAGE_ID"]}
).execute()

Stack trace

googleapiclient.errors.HttpError: <HttpError 403 when requesting
https://gmail.googleapis.com/gmail/v1/users/me/messages/batchDelete
returned "Request had insufficient authentication scopes.">

###Expected behavior

According to Gmail API documentation, deleting messages (moving them to Trash) should be permitted with the scope:
https://www.googleapis.com/auth/gmail.modify
Therefore, users.messages.batchDelete is expected to succeed with this scope.

###Observed behavior

users.messages.list works with gmail.modify
users.messages.modify (label changes) works with gmail.modify
users.messages.batchDelete consistently returns 403 insufficientPermissions

The same code succeeds immediately when using the broader scope:
https://mail.google.com/

This suggests batchDelete is guarded by stricter backend permissions than documented, or the documentation does not accurately reflect the required scope.

Making sure to follow these steps will guarantee the quickest resolution possible.

Thanks!