Claude API 인증을 OAuth 구독 모델로 전환한 리팩터링

Claude의 API 호출 방식을 전면 리팩터링했다. Anthropic 직접 호출에서 Claude Code OAuth 기반 구독 모델로 전환하면서 인증, 요청 처리, 의존성 관리 전반을 정리한 작업이다.

왜 이런 변경이 필요했나

처음엔 Anthropic API에 직접 키를 심고 호출하는 방식이었다. 하지만 이 방식은 몇 가지 한계가 있었다. 첫째, API 키 관리의 복잡성이 있다. 여러 환경에서 시크릿을 일관되게 유지하기 어렵고, 키 로테이션이나 권한 제어가 세밀하지 않다. 둘째, 구독 모델과의 연동이 필요해졌다. 사용자별 quota 제한, 월별 청구, 구독 등급에 따른 차등 처리 등이 직접 API 키 방식으로는 관리하기 까다롭다.

Claude Code OAuth로 전환하면, 사용자 인증과 구독 상태를 통합하게 된다. 이렇게 하면 각 사용자의 인증 토큰이 자동으로 그 사용자의 구독 정보(Max subscription 등)와 연결되고, 서버 단에서는 일관된 권한 검증만 하면 된다.

구체적으로 뭐가 바뀌었나

package.json 에서는 Anthropic SDK 의존성과 OAuth 인증을 위한 새 라이브러리들을 추가/교체했을 것으로 보인다. 단순히 @anthropic-ai/sdk 버전 업그레이드에 그치지 않고, OAuth 플로우를 담당할 라이브러리(예: oauth2 관련 의존성)나 토큰 관리 유틸이 들어왔을 가능성이 크다.

src/lib/anthropic.ts 는 이전의 "API 키로 직접 초기화 후 호출" 패턴에서 "사용자 OAuth 토큰으로 초기화" 방식으로 전환했을 것이다. 대략 이런 식이다:

// Before: API 키 직접 사용
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// After: OAuth 토큰 사용
const client = new Anthropic({
  apiToken: userOAuthToken, // 사용자별 토큰
  headers: {
    'X-Subscription-Plan': 'max', // 구독 정보 명시
  },
});

이렇게 되면, 같은 anthropic.ts 모듈이라도 호출할 때마다 다른 사용자 토큰을 넘겨 받거나, 인증 미들웨어에서 토큰을 주입하게 된다.

src/lib/claude-cli.ts 는 아마도 CLI 또는 로컬 개발 환경용 Claude 클라이언트일 텐데, 여기도 같은 원리로 OAuth 토큰을 받아서 초기화하게 바뀌었을 것 같다. 혹은 CLI 인증 플로우 자체가 들어갔거나, 환경 변수 대신 토큰 파일을 읽는 방식으로 개선되었을 수 있다.

이 변경이 시스템에 미친 영향

보안 관점

API 키가 노출되면 누구나 무제한 호출 가능했던 구조에서, 이제는 각 사용자의 토큰만 유효하다. 토큰은 시간 제한이 있을 가능성도 높고, 해당 사용자의 권한/구독 정보와 1:1 대응된다.

운영 관점

구독 모델(Max subscription)이 API 레이어에 정규화되면서, 서버 코드에서 "이 사용자가 Max 구독인지 확인" 같은 로직이 간단해진다. API 응답 헤더나 사용자 정보 엔드포인트에서 명시적으로 확인할 필요 없이, 토큰 자체가 그 정보를 담고 있다.

개발자 경험

OAuth 토큰 갱신, 만료 처리 같은 추가 복잡성이 생겼다. 하지만 반대로, 각 팀원이 자신의 credential을 관리하기 때문에 "공용 API 키 실수로 공개" 같은 사고는 줄어든다.

비슷한 상황에서 배운 점

API 직접 호출 → OAuth 기반 구독 모델로 전환하는 작업은 생각보다 영향도가 크다. 왜냐하면:

모든 요청 호출처를 찾아 수정해야 한다. 어딘가 빠진 게 있으면 old credential으로 호출되고 권한 에러가 난다.
테스트 환경과 로컬 개발 환경을 분리해야 한다. 테스트용 OAuth 토큰과 실제 사용자 토큰의 만료 정책이 다를 수 있다.
토큰 갱신 로직을 놓치기 쉽다. refresh token을 어떻게 관리할지, 만료됐을 때 재인증을 어떻게 할지 미리 설계하지 않으면 나중에 골치 아프다.

이번에는 이런 케이스들을 package.json 과 두 lib 파일 갱신으로 정리하면서, 점진적으로 테스트해볼 수 있도록 구성했다. 특히 claude-cli.ts 같이 로컬 개발용 진입점부터 OAuth 토큰 방식으로 변경하면, CI/CD 파이프라인에 반영하기 전에 손으로 검증할 수 있다.

회고

사이드 프로젝트라고 해도, 외부 서비스의 인증 방식 전환은 꽤 신중하게 접근해야 한다. 이 경우 Claude Code 구독 정보를 정확히 활용하기 위해 API 호출 구조를 깔끔하게 정리한 게 좋았다. 앞으로 사용자 기능이 늘어날 때, 구독 등급별로 다른 모델(Claude 3.5 vs Opus) 을 사용하거나, rate limiting 을 적용할 수도 있게 됐으니까.

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

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

Claude API 인증을 OAuth 구독 모델로 전환한 리팩터링

왜 이런 변경이 필요했나

구체적으로 뭐가 바뀌었나