OAuth 로그인 토큰과 API 키의 차이¶
한 줄 요약: 둘 다 "토큰"처럼 생긴 긴 문자열이지만, OAuth 로그인 토큰은 "그 계정으로 로그인한 상태"를 정해진 앱에 빌려주는 것이고, API 키는 개발자가 자기 프로그램에서 서비스를 부르라고 받는 열쇠다. 용도·과금·약관이 다르다.
📍 만난 상황¶
- 2026-11-11 11:11 — 학습 일지 자동화를 개인 GitHub에 연결하고 첫 push까지 마친 직후였다. 직전에 "장기 토큰을 등록하지 않으면 며칠 뒤 자동 실행이 멈출 수 있으니
claude setup-token으로 토큰을 등록하라"는 안내를 들었다. 그래서 "이 토큰을 API 토큰처럼 쓸 수 있는 거냐"고 물었다. 1번 물음 → 그날 일지 - 결론: 아니다. 사람 없이 Claude Code(
claude -p)를 돌리기 위한 로그인 토큰이다. 직접 만든 앱에서 API를 부르려면 API 키를 써야 한다.
🧩 쉽게 말하면¶
헬스장 회원 카드와 업체용 출입 계약을 떠올리면 된다.
- 회원 카드(OAuth 로그인 토큰): 내 월 회비(구독) 안에서 내가 헬스장을 쓰는 카드다. 친구에게 빌려주거나, 이 카드로 PT 사업을 차리면 안 된다.
- 업체 계약(API 키): 헬스장 시설을 내 사업에 쓰겠다고 맺은 계약이다. 쓴 만큼 정산한다.
카드도 계약서도 "출입증"처럼 보이지만 쓰는 사람, 쓰는 곳, 돈 내는 방식이 다르다. 이 구분이 없으면 "토큰이니까 아무 데나 넣으면 되겠지"라는 착각이 생긴다.
📖 제대로 알기¶
OAuth 로그인 토큰¶
OAuth(사용자가 비밀번호를 넘기지 않고 앱에 권한을 빌려주는 표준 규약)로 발급된 토큰이다. - 액세스 토큰(access token: 요청할 때 내미는 짧은 수명의 출입증) - 리프레시 토큰(refresh token: 액세스 토큰이 만료되면 새로 받는 데 쓰는 긴 수명의 토큰)
핵심은 "사람 계정의 권한을 위임받은 것"이라는 점이다. 그래서 발급한 사람의 계정과 요금제에 묶인다.
claude setup-token이 만드는 토큰이 이 종류다.
- 구독(Pro·Max·Team·Enterprise 등) 계정의 1년짜리 OAuth 토큰이다.
- 브라우저 로그인을 할 수 없는 스크립트·예약 작업·CI에서 Claude Code를 쓰라고 있는 것이다.
- 모델 요청만 된다. claude.ai 커넥터나 Remote Control은 안 된다.
API 키¶
API 키(API key: 개발자 콘솔에서 발급하는 프로그램용 자격 증명)는 "이 프로그램은 이 개발자 계정 소속"이라는 표시다.
- Anthropic이라면 Console에서 sk-ant-api…로 시작하는 키를 받는다.
- 직접 만든 앱, SDK, curl로 Messages API를 부를 때 쓴다.
- 쓴 토큰(모델 입출력 단위) 수만큼 종량 과금된다.
한눈에 보기¶
| 항목 | setup-token 토큰 |
API 키 |
|---|---|---|
| 정체 | 구독 계정의 OAuth 로그인 토큰 | 개발자용 키 |
| 과금 | 구독 사용량 한도 안 | 쓴 만큼 종량 |
| 쓰는 곳 | Claude Code (claude -p, Actions) |
직접 만든 앱, SDK |
| 필요 조건 | 유료 구독 | Console 계정과 결제수단 |
⚙️ 어떻게 동작하나¶
- 발급:
claude setup-token을 실행하면 브라우저에서 구독 계정으로 로그인한다. 승인하면 터미널에 긴 토큰이 한 번 출력된다. - 보관: 그 값을 비밀 저장소(macOS Keychain, GitHub Secrets 등)에 넣는다.
- 사용: 예약 작업이 실행될 때 토큰을 환경 변수로 넘기고
claude -p를 부른다. Claude Code는 이 토큰으로 "구독 계정으로 로그인한 상태"가 된다. - 과금: 요청은 그 계정의 구독 한도에서 차감된다. 같은 시간에 사람이 쓰는 대화형 Claude와 한도를 나눠 쓴다.
- 만료: 1년 뒤 만료된다. 그 전에 다시 발급해 바꿔 넣는다.
왜 이렇게 나눴을까? 구독은 "사람 한 명이 공식 앱으로 쓰는 양"을 기준으로 값이 정해져 있다. 이걸 다른 서비스의 뒷단에 붙이면 요금 체계가 무너진다. 그래서 제품을 만드는 쪽은 API 키, 본인이 공식 앱을 쓰는 쪽은 구독 로그인으로 길을 나눈다.
🧪 예시¶
- 예시 1 · 일상에 빗대어: 월 회비로 헬스장을 다닌다.
- 퇴근 뒤 혼자 1시간 운동 → 회원 카드로 OK. 일지 자동화가 이 경우다.
-
회원 카드로 손님 5명을 데려와 PT 수업을 한다 → 약관 위반이다. 직접 만든 서비스에 구독 토큰을 붙이는 경우가 이렇다.
-
예시 2 · 실제로는 (macOS Keychain에 넣고 꺼내 쓰기)
# ① 저장: -w 뒤에 값을 안 쓰면 입력 창에서 붙여 넣는다
security add-generic-password -a "$USER" -s claude-oauth-token -w
# ② 꺼내기: 값만 출력
TOKEN=$(security find-generic-password -s claude-oauth-token -w)
# ③ 실행할 때만 환경 변수로 넘김 (<비밀값> 자리에 ②에서 꺼낸 값을 넣는다)
CLAUDE_CODE_OAUTH_TOKEN="<비밀값>" claude -p "오늘 대화 정리해줘"
① 토큰을 명령줄에 직접 쓰지 않는다. 그러면 셸 기록(~/.zsh_history)에 남는다.
② 예약 작업 스크립트는 실행할 때마다 Keychain에서 꺼낸다. 파일에 적어 두지 않는다.
③ 환경 변수는 그 명령 한 번에만 적용된다.
API 키라면 쓰는 곳이 다르다.
import anthropic
client = anthropic.Anthropic() # ANTHROPIC_API_KEY 환경 변수를 읽음
msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=200,
messages=[{"role": "user", "content": "안녕"}])
① 직접 만든 프로그램이 SDK로 API를 부른다. ② 이 자리에는 API 키가 들어가야 한다. 구독 토큰을 넣는 건 허용된 용도가 아니다.
⚖️ 비교 · 흔한 오해¶
헷갈린 점: "토큰이면 다 API 호출에 쓸 수 있다" 이렇게 생각하기 쉬운 이유가 있다. 둘 다 긴 문자열이고, 둘 다 요청 헤더에 실려 서버로 간다. 겉모양만 보면 구별할 방법이 없다.
차이는 문자열이 아니라 누구의 어떤 권한을 대표하느냐에 있다. 로그인 토큰은 "이 사람이 공식 앱을 쓰는 중"을, API 키는 "이 개발자의 프로그램"을 대표한다.
그래서 구독 토큰을 curl이나 SDK에 넣으면 기술적으로 될지 몰라도 약관상 허용되지 않고, 언제든 막힐 수 있다.
| 상황 | 맞는 자격 증명 |
|---|---|
내 Mac에서 내 대화를 claude -p로 정리 |
구독 로그인 토큰 |
| GitHub Actions에서 내 저장소용 Claude Code 실행 | 구독 로그인 토큰 |
| 회사 서비스에 Claude 기능 넣기 | API 키 |
| 남의 요청을 대신 처리하는 봇 | API 키 |
다른 흔한 오해 - "API 키가 더 강력하다" → 강하고 약한 문제가 아니라 쓰는 곳이 다르다. 둘 다 유출되면 남이 내 돈(구독 한도나 종량 요금)을 쓴다. - "1년짜리라 편하다" → 오래 유효한 만큼 유출 피해도 길다. 보관이 더 중요해진다.
🛠️ 실무에서는¶
- 고르는 기준: "내가 공식 앱을 쓰는가, 내 프로그램이 API를 부르는가?" 앞이면 로그인 토큰, 뒤면 API 키.
- 보관 체크리스트
- 저장소(repo)나 설정 파일에 넣지 않는다. Keychain, Secrets 같은 비밀 저장소에 둔다.
- 대화, 로그, 스크린샷에 값을 남기지 않는다.
- 유출이 의심되면 바로 폐기하고 새로 발급한다.
- 한도 관리: 구독 토큰으로 돌리는 예약 작업은 사람이 일하는 시간과 한도를 나눠 쓴다. 무거운 작업은 사람이 덜 쓰는 시간에 둔다.
- 문제가 생기면 먼저 볼 것: 인증 실패면 만료일과 환경 변수 이름을 확인한다. 같은 환경에 API 키 환경 변수가 함께 있으면 어느 쪽이 쓰였는지(구독 한도인지 종량 과금인지)도 확인한다.
❓ 자주 묻는 질문¶
- Q. 회사 Team 요금제에서도
setup-token을 쓸 수 있나? A. Team·Enterprise도 구독이라 발급 대상이다. 다만 회사 계정이면 회사 정책을 먼저 따른다. - Q. GitHub Actions에 넣어도 되나? A. 본인 저장소에서 Claude Code를 돌리는 용도라면 공식 문서가 안내하는 사용법이다. 값은 repo Secrets에 넣는다.
- Q. 1년이 지나면 자동 실행이 어떻게 되나? A. 인증이 실패해 멈춘다. 만료 전에 다시 발급해 Keychain 값을 바꾼다. 달력에 갱신일을 적어 두면 좋다.
🔭 더 깊이 보기¶
- OAuth의 액세스 토큰과 리프레시 토큰은 왜 나눠 두나? — 토큰 수명과 보안의 균형을 이해하는 출발점이다.
- 사람 계정 대신 쓰는 "서비스 계정"은 무엇이 다른가? — 회사 시스템에서 자동화할 때 맞는 자격 증명을 고를 수 있다.
- 비밀값을 코드 밖에 두는 방법(Secrets 관리)은 어떤 것들이 있나? — 토큰이 늘어날수록 필요해진다.
- 관련 주제: CLI headless 실행과 claude -p · cron 예약 실행과 클라우드 실행 · OIDC 로그인 흐름 · SSO 로그인과 쿠키 세션 유지
📚 참고 자료¶
- Authentication (Claude Code 공식 문서, 영문) — 구독 로그인,
setup-token, API 키 설정 방법 · 링크 - Legal and compliance (Claude Code 공식 문서, 영문) — 구독 로그인과 API 키의 허용 용도 · 링크
- RFC 6749 The OAuth 2.0 Authorization Framework (IETF, 영문) — 액세스·리프레시 토큰의 원래 정의 · 링크
🗓️ 이력¶
- 2026-11-11:
claude setup-token토큰을 API 키처럼 쓸 수 있는지 물음 → 일지