Sửa lỗi 'Request had insufficient authentication scopes' (403 Forbidden) trong Google Sheets API

Thông Báo Lỗi

Lỗi này thường xuất hiện ngay khi bạn chuyển từ việc đọc dữ liệu sang cố gắng chỉnh sửa nó. Bạn sẽ thấy phản hồi 403 Forbidden trong terminal hoặc log trông như thế này:

{
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCESS_TOKEN_SCOPE_INSUFFICIENT",
        "domain": "googleapis.com",
        "metadata": {
          "service": "sheets.googleapis.com",
          "method": "google.apps.sheets.v4.SpreadsheetsService.GetSpreadsheet"
        }
      }
    ]
  }
}

Về cơ bản, API đang nói với bạn rằng: "Tôi biết bạn là ai, nhưng bạn không có quyền thực hiện thao tác đó ở đây."

Nguyên Nhân Gốc Rễ

Hãy nghĩ về OAuth2 scopes như những chìa khóa riêng biệt cho từng căn phòng. Nếu bạn chỉ xin chìa khóa vào "Sảnh", bạn không thể bước vào "Két Sắt". Lỗi này xảy ra khi access token của bạn thiếu các quyền cụ thể mà phương thức API bạn đang gọi yêu cầu.

Các nguyên nhân phổ biến bao gồm:

• Quyền Không Khớp: Bạn khởi tạo ứng dụng với spreadsheets.readonly nhưng vừa cố thực thi lệnh gọi spreadsheets.values.append.
• Token Cũ: Bạn đã cập nhật mảng SCOPES trong code, nhưng ứng dụng vẫn đang dùng token cũ được lưu trong cache từ lần chạy đầu tiên.
• Hạn Chế File: Bạn đang cố truy cập một file mà ứng dụng không tạo ra mà không có scope drive hoặc spreadsheets đủ rộng.

Cách Khắc Phục Lỗi

1. Cập Nhật Scopes Trong Source Code

Trước tiên, hãy xác định chính xác mức quyền truy cập mà script của bạn cần. Sử dụng scope hạn chế nhất có thể là một best practice, nhưng nó phải đủ để thực hiện tác vụ. Đối với Google Sheets, đây là các tùy chọn tiêu chuẩn:

• Chỉ đọc: .../auth/spreadsheets.readonly (Xem spreadsheet và thuộc tính)
• Đọc/Ghi: .../auth/spreadsheets (Đọc, chỉnh sửa và tạo spreadsheet)
• Giới hạn File: .../auth/drive.file (Chỉ truy cập các file được mở hoặc tạo bởi ứng dụng của bạn)

Trong script Python sử dụng google-auth, bạn sẽ thay đổi định nghĩa như sau:

# Scope hạn chế cũ:
SCOPES = ['https://www.googleapis.com/auth/spreadsheets.readonly']

# Scope mới để ghi/chỉnh sửa:
SCOPES = ['https://www.googleapis.com/auth/spreadsheets']

2. Xóa Token Đã Lưu Cache (Bước Quan Trọng)

Thay đổi code mới chỉ giải quyết được một nửa vấn đề. Hầu hết các thư viện Google lưu trữ access_token và refresh_token cục bộ để tránh phải đăng nhập liên tục. File này (thường là token.json, token.pickle, hoặc credentials.json) vẫn chứa quyền hạn cũ bị giới hạn của bạn.

Bạn phải xóa file token cục bộ này theo cách thủ công.

Sau khi xóa, hãy khởi động lại script. Thao tác này buộc luồng OAuth2 phải kích hoạt trên trình duyệt của bạn. Bạn sẽ thấy màn hình xác nhận quyền mới liệt kê các quyền nâng cao. Khi phê duyệt, một token mới với các scope chính xác sẽ được tạo ra, giải quyết ngay lập tức lỗi 403.

3. Đồng Bộ Với Google Cloud Console

Đối với các ứng dụng đang chạy thực tế, các scope bạn yêu cầu phải khớp với những gì bạn đã khai báo trong cài đặt dự án. Sự không nhất quán ở đây có thể dẫn đến cảnh báo xác minh hoặc lỗi hoàn toàn.

• Mở Google Cloud Console.
• Đi đến APIs & Services > OAuth consent screen.
• Chọn Edit App và kéo xuống phần Scopes.
• Đảm bảo https://www.googleapis.com/auth/spreadsheets đã được thêm vào và lưu lại.

Kiểm Tra Kết Quả

Thực hiện các bước sau để đảm bảo việc sửa lỗi là vĩnh viễn:

• Chạy script và chờ trình duyệt chuyển hướng.
• Đọc kỹ danh sách quyền trên trang đăng nhập Google. Lúc này nó phải hiển thị rõ ràng: "See, edit, create, and delete all your Google Sheets spreadsheets."
• Kiểm tra thư mục của bạn để xem có file token.json mới được tạo ra không.
• Thực thi lệnh gọi API. Trạng thái 200 OK có nghĩa là mọi thứ đã hoạt động trở lại.

Bảo Mật và Phòng Ngừa

Quản lý nhiều môi trường thường dẫn đến tình trạng scope bị lệch theo thời gian. Tôi khuyến nghị dùng biến môi trường để lưu trữ các scope. Cách này giúp bạn dễ dàng chuyển đổi quyền giữa môi trường dev cục bộ và server production hơn.

Nếu bạn đang xây dựng hệ thống yêu cầu Service Account hoặc cấu hình OAuth phức tạp, bảo mật là yếu tố hàng đầu. Khi cấu hình các file môi trường, tôi dùng Password Generator tại ToolCraft để tạo các chuỗi entropy cao, duy nhất cho các secret nội bộ của ứng dụng. Đây là cách đơn giản để tránh dùng các placeholder yếu thường bị quên lại trong codebase.

Luôn tuân thủ Nguyên Tắc Đặc Quyền Tối Thiểu. Nếu bạn chỉ cần chỉnh sửa một sheet mà ứng dụng đã tạo, hãy dùng drive.file. Chỉ dùng đến scope spreadsheets đầy đủ khi bạn thực sự cần truy cập bất kỳ file nào trong thư viện của người dùng. Điều này giúp hạn chế rủi ro nếu token bị lộ.