구글 API 자동화가 7일마다 invalid_grant로 끊길 때

작성자:
한눈에 보기

겪은 일: 구글 API로 자료를 받던 예약 작업이 어느 날 invalid_grant를 내며 "다시 인증하라"고 멈췄습니다.

원인: OAuth 앱의 사용자 유형이 "외부"이고 게시 상태가 "테스트"면, 갱신 토큰이 발급 7일 뒤 만료됩니다.

이렇게 풀었다: Google 인증 플랫폼의 "대상"에서 앱을 게시하고, 게시한 뒤 한 번 다시 인증해 둡니다.

잘 돌던 예약 작업이 일주일 만에 멈췄다

서치콘솔이나 분석 자료처럼 구글 계정 권한을 받아 도는 스크립트는 처음 한 번 브라우저에서 허용을 누르고, 그때 받은 갱신 토큰(refresh token)으로 계속 돕니다. 그런데 며칠 잘 돌던 예약 작업이 토큰을 갱신하다 아래 오류로 멈췄습니다.

invalid_grant

앱을 게시하려고 콘솔에 들어갔더니 "앱 게시" 단추가 회색이라 누를 수 없었습니다. 다른 API 하나는 서비스 계정 키로 붙여 보니 "이 프로젝트에서 API가 꺼져 있다"가 나왔고, 켜려 해도 막혔습니다.

세 가지 모두 처음에는 서로 다른 문제처럼 보였지만, 뿌리는 구글 인증 방식 두 가지(OAuth 사용자 인증과 서비스 계정)를 구분하지 않은 데 있었습니다. 아래에서 하나씩 나눠 봅니다.

테스트 상태 앱의 7일 만료

구글 OAuth 문서의 "Refresh token expiration" 부분에 따르면, 사용자 유형이 외부이고 게시 상태가 테스트인 앱의 갱신 토큰은 발급 7일 뒤 만료됩니다. 예외는 이름, 이메일, 프로필 범위만 요청하는 앱뿐입니다. 자료를 읽는 범위를 쓰면 여기에 걸립니다.

증상 원인
7일마다 invalid_grant 외부 사용자 유형 + 테스트 게시 상태
"앱 게시" 단추가 회색 브랜딩의 별표 없는 칸(홈페이지, 개인정보처리방침 링크, 서비스 약관 링크, 승인된 도메인)이 비어 있다
서비스 계정으로 "API가 꺼져 있다" 그 API가 서비스 계정을 아예 받지 않고 OAuth 설치형 앱 흐름만 받는다

세 번째는 따로 알아 둘 만합니다. 서치콘솔 API는 서비스 계정 키로 잘 되는데, 애드센스 Management API는 서비스 계정을 지원하지 않습니다. 오류가 "권한 없음"이 아니라 "API가 꺼져 있다"로 나와서 헤매기 쉽습니다.

앱을 게시하고 다시 인증한다

  1. 구글 클라우드 콘솔에서 Google 인증 플랫폼, 대상(영어 화면 Google Auth Platform, Audience)으로 갑니다.
  2. 맨 위 "게시 상태"가 테스트면 "앱 게시" 단추가 있습니다. 회색이면 브랜딩 메뉴에서 별표 없는 칸까지 채웁니다. 로고는 비워 두었습니다.
  3. 게시하면 상태가 "프로덕션 단계"로 바뀌고, 단추는 "테스트로 돌아가기"가 됩니다.
  4. 게시한 뒤 한 번 다시 인증해 새 토큰을 받습니다.
https://console.cloud.google.com/auth/audience?project=<프로젝트 ID>

4번은 공식 문서에 적혀 있지 않습니다. 테스트 때 받은 토큰이 게시 뒤에도 7일에 끊기는지는 문서로 확인하지 못했고, 개발자 포럼 경험담이 "다시 인증해야 오래 가는 토큰을 받는다" 쪽이라 안전하게 다시 인증했습니다.

몇 가지 더 알아 둘 것이 있습니다. 데스크톱 앱의 client secret은 만든 순간 한 번만 보이니 그 창에서 JSON을 받아 둡니다. 구글 검증을 받지 않은 앱은 허용할 때 "확인되지 않은 앱" 경고가 뜨고, 새 사용자가 프로젝트 평생 100명으로 막힙니다. 몇 개 계정으로 쓰는 개인 도구라면 이대로 써도 됩니다.

다시 끊기지 않는지 확인하는 법

대상 화면에서 게시 상태가 "프로덕션 단계"인지 봅니다. 9월 11일에 본 화면은 프로덕션 단계, 사용자 한도 100명 중 4명이었습니다. 그리고 끊긴 것을 사람이 바로 알게, 토큰 갱신에 실패하면 알림을 보내게 해 둡니다.

from google.auth.exceptions import RefreshError
try:
    creds.refresh(request)
except RefreshError as e:
    send_alert(f"구글 토큰 갱신 실패: {e}")
    raise

예약 작업이 조용히 멈추면 며칠 뒤에야 알게 됩니다. 크론이 돌았다고 일이 된 것은 아니라는 이야기는 크론이 도는데 아무 일도 안 할 때에 적었습니다.

2단계 인증을 켜도 서비스 계정은 멈추지 않는다

구글 계정에 2단계 인증을 켜면 자동화가 멈출까 걱정했습니다. 구글 문서는 이 의무화가 사람 로그인에만 적용되고 서비스 계정에는 영향이 없다고 적고 있습니다. 실제로 켠 직후 서비스 계정 호출이 HTTP 200으로, 켜기 전과 같았습니다. 서비스 계정으로 서치콘솔을 읽는 법은 URL 검사 API 글에서도 이어집니다.

확인한 환경

항목 값
도구 구글 클라우드 콘솔(Google 인증 플랫폼), OAuth 데스크톱 앱
확인한 날짜 2026년 9월 11일(게시 상태 화면), 7월 31일(2단계 인증 뒤 호출)

이 글의 내용은 2026년 10월 5일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.