GSC API 권한 범위 오류를 트래픽 감시 스크립트에서 수정한 과정

traffic-watcher 스크립트가 Google Search Console(이하 GSC) API와 통신하며 invalid_scope 에러를 던질 때 대응한 작은 수정이다. 권한 범위를 webmasters.readonly에서 webmasters로 확대했다. 단 한 줄 짜리 커밋처럼 보이지만, 그 안에 외부 API 통합 시 놓치기 쉬운 여러 패턴이 숨어 있다.

외부 API 권한 설계의 흔한 함정

GSC API 연동을 시작할 때 대부분 최소 권한 원칙(principle of least privilege)에 따라 webmasters.readonly 권한으로 시작한다. 모니터링 용도니까 읽기만 필요하다고 생각하기 쉽기 때문이다. 하지만 실제 서비스 요구사항을 만나면 이게 부족할 때가 있다.

invalid_scope 에러는 "네가 현재 가진 권한으로는 이 작업을 할 수 없다"는 신호다. GSC의 경우:
- webmasters.readonly: 데이터 읽기만 가능 (검색 트래픽, 키워드 분석 등)
- webmasters: 읽기 + 쓰기 권한 (설정 변경, 소유권 검증 등)

traffic-watcher가 단순 모니터링을 넘어 일부 설정 조작이나 API 엔드포인트 접근이 필요했던 것 같다. readonly로는 그 작업이 불가능해서 scope 확대가 불가피했다.

팀 레벨에서 배운 패턴

이런 류 수정이 반복되는 걸 보면:

1. API 문서 검증의 중요성
연동 초기에 실제 필요한 모든 엔드포인트를 테스트해야 한다. 개발 단계에서는 readonly로도 충분해 보이지만, 운영 시나리오(예: 자동화된 재크롤링 요청, 인덱싱 상태 갱신)를 함께 고려해야 한다.

2. 권한 설정 체크리스트 추가
스크립트 배포 전에 다음을 확인하는 프로세스를 넣었다:
- 실제 사용할 모든 API 호출 나열
- 각 호출에 필요한 최소 scope 확인
- 테스트 환경에서 충분한지 사전 검증

3. 에러 핸들링 개선
invalid_scope 같은 권한 에러는 retry 불가능한 영구 에러다. 이런 경우 팀 알림 → 권한 재검토 → 재배포 같은 정해진 플로우가 필요했다.

외부 API 권한 설정 — 실무 체크리스트

회고

작은 수정이지만 여러 곳에 영향을 미쳤다:
- 코드: traffic-watcher 스크립트 한 줄 변경
- 권한 관리: GSC 연동 계정의 scope 재설정
- 모니터링: invalid_scope 같은 권한 에러 자동 감지 추가
- 문서화: 왜 webmasters 권한이 필요한지 스크립트 코멘트 추가

특히 팀원들과 리뷰할 때 "최소 권한이 좋지만, 실제 기능 요구사항을 무시해서도 안 된다"는 균형 맞추기의 중요성을 이야기했다. 보안과 실용성은 대립이 아니라, 정보 기반 의사결정(informed trade-off)의 문제라는 점을 강조.

다음번 외부 API 연동부터는 "권한 요구사항 분석" 체크리스트를 정해서 같은 시행착오를 줄일 계획.

🛒 이 글과 어울리는 추천 상품

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 책상조명 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.