YouTube Data API OAuth 인증 설정: 로컬 자동 업로더 연결하기

YouTube 영상을 코드로 업로드하려면 API 키만으로는 부족합니다. 영상 업로드, 썸네일 지정, 자막 등록처럼 채널 데이터를 바꾸는 작업은 채널 소유자의 동의를 받은 OAuth 2.0 인증이 필요합니다.

이 글에서는 로컬에서 실행하는 자동 업로더를 기준으로 Google Cloud 설정부터 최초 인증, 장기 운영 시 주의점까지 한 번에 정리합니다. 실제 클라이언트 정보나 토큰 값은 다루지 않습니다.

왜 이 주제가 중요한가

자동 업로드에서 가장 자주 막히는 지점은 코드보다 인증 설정입니다. 앱 유형을 잘못 고르거나, 테스트 사용자를 빠뜨리거나, 필요한 권한 범위를 누락하면 브라우저 동의 단계 또는 업로드 단계에서 오류가 납니다.

또한 OAuth 앱 검증과 YouTube API 규정 준수 감사는 서로 다른 절차입니다. 인증이 성공했다고 해서 새 API 프로젝트가 곧바로 공개 영상을 자동 업로드할 수 있는 것은 아닙니다. 개발 초기부터 두 절차를 구분해 두면 운영 전환 때 시행착오를 크게 줄일 수 있습니다.

핵심 개념

사용자 OAuth가 필요한 이유

일반 YouTube 채널은 서비스 계정으로 대신 로그인할 수 없습니다. 채널을 소유하거나 관리하는 Google 계정이 브라우저에서 직접 동의해야 합니다. 동의가 끝나면 애플리케이션은 액세스 토큰을 사용하고, 만료된 뒤에는 갱신 토큰으로 새 액세스 토큰을 발급받습니다.

로컬에서 사람이 최초 인증을 진행하는 도구라면 OAuth 클라이언트 유형은 데스크톱 앱이 자연스럽습니다. 인증 과정에서 시스템 브라우저가 열리고, 완료 결과는 로컬 리디렉션으로 돌아옵니다.

작업별 권한 범위

권한은 필요한 만큼만 요청하는 것이 원칙입니다.

작업	권장 범위
영상 업로드	https://www.googleapis.com/auth/youtube.upload
맞춤 썸네일 지정	youtube.upload 범위로 처리 가능
별도 SRT 자막 업로드	https://www.googleapis.com/auth/youtube.force-ssl 추가

영상에 자막을 입혀서 내보내는 것만으로 충분하다면 별도 자막 API 권한은 생략할 수 있습니다. 반대로 YouTube 플레이어에서 켜고 끌 수 있는 자막 트랙이 필요하다면 captions.insert 호출과 youtube.force-ssl 범위가 필요합니다.

실제 적용 포인트

1. Google Cloud 프로젝트와 API 준비

1. Google Cloud Console에서 전용 프로젝트를 선택하거나 새로 만듭니다.
2. API 및 서비스의 라이브러리에서 YouTube Data API v3를 찾아 활성화합니다.
3. Google Auth Platform의 Branding에서 앱 이름과 지원 연락처를 설정합니다.
4. Audience에서 외부 사용자를 선택하고, 개발 중에는 Testing 상태로 둡니다.
5. 테스트 사용자에 실제 업로드할 YouTube 채널의 Google 계정을 추가합니다.
6. Data Access에서 영상 업로드에 필요한 범위를 등록하고, 별도 자막이 필요할 때만 youtube.force-ssl을 추가합니다.

Google 계정 하나가 여러 YouTube 채널이나 브랜드 계정을 관리한다면 최초 동의 때 실제 업로드 대상 채널을 정확히 선택해야 합니다.

2. 데스크톱 앱 OAuth 클라이언트 만들기

Clients 메뉴에서 OAuth client ID를 만들고 애플리케이션 유형으로 Desktop app을 선택합니다. 내려받은 클라이언트 설정 파일은 소스 코드와 분리해 보관합니다.

권장 구조는 다음과 같습니다.

project/
  .secrets/
    youtube-client.json
    youtube-token.json

버전 관리 제외 규칙에는 다음 한 줄을 추가합니다.

.secrets/

클라이언트 설정 파일과 갱신 토큰 파일은 모두 인증 정보입니다. Git 저장소, 메신저, 공개 문서, 빌드 산출물에 포함하지 말고 파일 권한도 최소화해야 합니다.

3. 최초 인증 실행

업로더를 처음 실행하면 시스템 브라우저가 열립니다. 테스트 사용자로 등록한 Google 계정으로 로그인하고, 올바른 YouTube 채널을 선택한 뒤 요청된 권한에 동의합니다.

성공하면 애플리케이션은 갱신 토큰을 로컬 비밀 저장 경로에 보관합니다. 이후에는 매번 브라우저를 열지 않고도 새 액세스 토큰을 받을 수 있습니다. 다만 사용자가 권한을 철회하거나 앱 상태가 바뀌면 다시 인증해야 할 수 있습니다.

4. 비공개 업로드로 전체 흐름 검증

처음부터 공개 업로드를 시도하기보다 다음 순서로 검증하는 편이 안전합니다.

1. 짧은 테스트 영상을 비공개 상태로 업로드합니다.
2. 제목, 설명, 태그가 의도대로 저장되는지 확인합니다.
3. 맞춤 썸네일을 설정합니다.
4. 필요한 경우 SRT 자막을 별도 트랙으로 등록합니다.
5. YouTube Studio에서 영상과 자막을 직접 재생해 확인합니다.

각 단계가 독립적으로 성공하는지 기록하면 인증 오류와 미디어 처리 오류를 구분하기 쉽습니다.

주의할 점

Testing 상태의 갱신 토큰

외부 사용자용 OAuth 앱이 Testing 상태이고 YouTube 권한처럼 기본 로그인 범위를 넘어서는 권한을 요청하면 갱신 토큰이 일반적으로 7일 뒤 만료될 수 있습니다. 장기간 무인 실행이 필요하다면 Production 전환과 OAuth 검증 필요 여부를 미리 확인해야 합니다.

OAuth 검증과 YouTube API 감사는 별개

Google OAuth 검증은 앱이 요청하는 사용자 데이터 접근 범위를 심사하는 절차입니다. 이와 별도로 YouTube Data API의 videos.insert를 사용하는 검증되지 않은 새 API 프로젝트는 업로드 영상이 비공개로 제한될 수 있습니다. 공개 상태 자동 업로드가 목표라면 YouTube API Services Audit and Quota Extension Form을 통한 규정 준수 감사 필요 여부를 확인해야 합니다.

자주 만나는 오류

• 접근 차단: Audience 설정과 테스트 사용자 등록 여부를 확인합니다.
• 권한 부족: 실행한 작업과 요청한 OAuth 범위를 비교합니다.
• invalid_grant: 갱신 토큰의 만료, 철회 또는 앱 상태 변경을 확인하고 필요하면 다시 인증합니다.
• 영상이 비공개로만 등록됨: OAuth 문제가 아니라 API 프로젝트의 감사 제한일 수 있습니다.
• 다른 채널에 업로드됨: 최초 동의 때 선택한 Google 계정과 YouTube 채널을 다시 확인합니다.

듀오랩스가 보는 관점

자동 업로드는 최초 사용자 동의와 반복 실행을 분리해서 설계하는 것이 좋습니다. 최초 인증은 사람이 화면을 보며 진행하고, 반복 업로드는 최소 권한과 안전한 비밀 저장소를 사용해 실행합니다. 권한이 늘어날수록 운영 부담도 커지므로 영상 업로드, 썸네일, 별도 자막의 필요성을 나눠 판단하는 편이 좋습니다.

공개 자동화의 기준은 단순히 API 호출이 성공하는지가 아닙니다. 올바른 채널 선택, 비공개 시험 업로드, 메타데이터 검수, 토큰 보호, 앱 검증, YouTube 정책 준수까지 한 흐름으로 확인해야 안정적인 운영이 가능합니다.

최종 체크리스트

• YouTube Data API v3 활성화
• 앱 Branding과 Audience 설정
• 테스트 사용자에 업로드 계정 추가
• Desktop app OAuth 클라이언트 생성
• youtube.upload 범위 적용
• 별도 자막이 필요할 때만 youtube.force-ssl 추가
• 클라이언트 파일과 토큰 파일을 버전 관리에서 제외
• 비공개 영상으로 업로드·썸네일·자막 검증
• 장기 운영 전 Production 전환과 OAuth 검증 검토
• 공개 자동 업로드 전 YouTube API 감사 필요 여부 확인

공식 문서

• YouTube Data API OAuth 2.0 인증
• 설치형 앱 OAuth 흐름
• 영상 업로드 가이드
• videos.insert 참조
• thumbnails.set 참조
• captions.insert 참조
• Google OAuth 2.0 정책과 토큰 수명