claude api key 발급 — 키 종류와 안 될 때
Claude API 키는 Claude 콘솔의 platform.claude.com/settings/keys에서 Create key를 눌러 만듭니다. 키는 sk-ant-로 시작하고, 만드는 그 순간 한 번만 보여 주고 다시는 안 보여 줍니다. 예전 안내와 달라진 건 두 가지입니다 — 만들 때 키 종류(개인 / 서비스 계정 / 워크스페이스)와 만료 기한을 고르게 되어 있고, 만료 기한은 만든 뒤에는 바꿀 수 없습니다. 발급 절차부터 키가 살아 있는지 확인하는 명령, 안 될 때 돌아오는 응답까지 실제로 호출해 본 결과로 정리했습니다. (2026년 9월 6일 공식 문서 확인)
claude api key 발급 — 어디서 만드나
발급 창구는 Claude 콘솔 한 곳입니다. 클로드 웹 채팅 화면(claude.ai)에는 API 키 메뉴가 없으니 주소를 잘못 찾아 헤매지 마세요.
- platform.claude.com에 로그인합니다. 계정이 없으면 여기서 만듭니다.
- 왼쪽에서 Settings → API keys로 들어갑니다. (바로가기: platform.claude.com/settings/keys)
- Create key를 누르고 이름 · 만료 기한 · 연결 계정(Linked account)을 정합니다. 키를 특정 워크스페이스로 묶고 싶으면 여기서 고릅니다.
- 화면에 뜬
sk-ant-로 시작하는 전체 문자열을 복사해 안전한 곳에 넣습니다.
키 종류 3가지 — 개인 키 · 서비스 계정 키 · 워크스페이스 키
예전에는 그냥 키 하나였는데, 지금은 만들 때 이 키가 누구 자격으로 동작하는지를 고르게 되어 있습니다. 이게 나중에 "잘 쓰던 키가 갑자기 죽는" 상황을 가릅니다.
| 키 종류 | 누구 자격으로 동작하나 | 언제 죽나 |
|---|---|---|
| 개인 키 (personal) |
나 자신. 내 역할·권한을 그대로 따라감 | 내가 조직에서 빠질 때. 조직에서 제거되면 보관 처리되고, 다시 초대받아도 되살아나지 않음(새로 만들어야 함) |
| 서비스 계정 키 (service account) |
사람이 아닌 서비스 계정. CI 파이프라인·운영 서버·에이전트용 | 그 서비스 계정이 보관 처리되거나, 단일 워크스페이스 키라면 그 워크스페이스에서 빠질 때 |
| 워크스페이스 키 (레거시) |
소유자 없음. 만들어진 워크스페이스에 귀속 | 만료·비활성화·삭제되거나 워크스페이스가 보관될 때. 만든 사람이 나가도 계속 동작 |
고르는 기준은 간단합니다. 내가 혼자 개발용으로 쓸 거면 개인 키, 팀이 같이 쓰거나 서버에 박아 둘 거면 서비스 계정 키입니다. 워크스페이스 키는 소유자가 없어서 편해 보이지만 공식 문서가 레거시로 분류하고 개인·서비스 계정 키를 권합니다. 계정이 조직에서 빠지면 자동으로 같이 죽는 쪽이 안전하기 때문입니다.
만료 기한 — 만든 뒤에는 못 바꾼다
키를 만들 때 만료 기한을 고릅니다. 프리셋은 3시간 · 1일 · 7일 · 30일이고, 직접 기간을 넣거나 Never(만료 없음)로 둘 수도 있습니다. 조직에 최대 만료 정책이 걸려 있으면 그 한도까지만 고를 수 있고 Never는 아예 안 보입니다.
만료가 다가오면 키를 만든 사람에게 메일이 갑니다. 수명 14일 이상으로 만든 키는 만료 7일 전에, 7일 이상인 키는 1일 전에 옵니다. 그보다 짧은 키는 예고 메일 없이 그냥 만료됩니다. 3시간짜리로 만들어 두고 다음 날 "어제까지 되던 키가 안 된다"고 헤매는 게 여기서 나옵니다. 만료된 키로 호출하면 401 authentication_error가 돌아오고, 만료된 키는 되살릴 수 없습니다 — 새로 만들어야 합니다.
발급한 키가 되는지 확인하는 법
키를 만들었으면 한 줄로 살아 있는지 확인하는 게 빠릅니다. 메시지를 생성하지 않고 모델 목록만 받아오는 GET /v1/models가 확인용으로 가볍습니다.
curl https://api.anthropic.com/v1/models \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"여기서 anthropic-version 헤더를 빼먹지 마세요. 그리고 키는 주소 뒤 ?key=가 아니라 헤더로 보냅니다.
실제로 메시지를 보내 보려면 POST /v1/messages입니다.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 64,
"messages": [{"role": "user", "content": "안녕"}]
}'환경변수로 두기 — ANTHROPIC_API_KEY
공식 문서가 권하는 방식은 코드에 키를 적지 않고 환경변수로 넘기는 것입니다. 변수 이름은 ANTHROPIC_API_KEY이고, 공식 클라이언트 라이브러리가 이 값을 알아서 읽어 갑니다.
# macOS / Linux (bash)
export ANTHROPIC_API_KEY="sk-ant-api03-발급받은키"
# Windows PowerShell — 지금 창에서만
$env:ANTHROPIC_API_KEY = "sk-ant-api03-발급받은키"
# Windows — 계정에 저장(다음부터 계속)
setx ANTHROPIC_API_KEY "sk-ant-api03-발급받은키"setx로 넣으면 지금 열려 있는 창에는 안 잡힙니다. 직접 확인해 봤습니다 — setx로 저장한 직후 같은 창에서 $env:변수명을 찍으면 빈 값이고, 사용자 환경변수에는 정상적으로 저장돼 있습니다. 터미널을 새로 열어야 반영됩니다. "분명히 넣었는데 키가 없다고 나온다"의 상당수가 이겁니다.
파이썬에서는 인자를 안 넘겨도 됩니다. 환경변수가 잡혀 있으면 그대로 읽어 갑니다. (아래는 anthropic 1.4.0 · Python 3.12 기준)
import anthropic
client = anthropic.Anthropic() # ANTHROPIC_API_KEY 를 자동으로 읽음
msg = client.messages.create(
model="claude-sonnet-5",
max_tokens=64,
messages=[{"role": "user", "content": "안녕"}],
)
print(msg.content[0].text)키가 안 될 때 — 응답으로 원인 가리기
잘못된 키, 헤더를 아예 안 보낸 경우 등으로 실제로 호출해 봤습니다. 같은 401이어도 메시지가 다르게 돌아오기 때문에 응답만 봐도 어디가 문제인지 갈립니다.
| 상황 | 돌아온 응답 (직접 확인) | 할 일 |
|---|---|---|
| 키 헤더를 안 보냄 | 401 · x-api-key header is required |
헤더 이름 오타 확인. 환경변수가 비어 있어 빈 값이 나간 경우도 여기 |
| 틀린 키 · 만료된 키 · 폐기한 키 | 401 · API key is invalid. |
콘솔에서 키 상태·만료일 확인. 만료됐으면 새 키를 만든다(되살릴 수 없음) |
키 자체 문제가 아닌 것들은 다른 번호로 옵니다. 여기서부터는 키를 다시 만들어도 소용이 없습니다.
| 코드 | 타입 | 뜻 |
|---|---|---|
| 402 | billing_error |
결제·청구 정보에 문제. 콘솔의 결제 정보를 확인하라는 뜻이지, 키가 잘못된 게 아니다 |
| 403 | permission_error |
키는 유효한데 그 자원을 쓸 권한이 없음. 조직·워크스페이스 설정을 본다 |
| 429 | rate_limit_error |
요청 속도 한도, 또는 티어의 월 지출 상한에 걸림 |
| 400 | invalid_request_error |
요청 형식 문제. 직접 설정해 둔 지출 한도에 닿아도 400이 온다 |
코드별 원인을 더 파고들 일이 생기면 클로드 코드 api 에러 글에 번호별로 정리해 뒀으니 같이 보세요.
Create key 버튼이 회색으로 눌리지 않을 때
키를 만들려고 들어갔는데 Create key 버튼 자체가 비활성화되어 있는 경우가 있습니다. 공식 문서는 이걸 내 역할(role)이 그 자리에서 키를 만들 수 있는 권한이 아닌 것이라고 설명합니다. 브라우저를 바꾸거나 새로고침해서 될 일이 아닙니다.
- 조직 관리자에게 내 역할 변경을 요청하거나,
- 관리자가 대신 서비스 계정 키를 만들어 넘겨주도록 요청합니다.
파이썬 SDK에서 나는 에러 두 가지
SDK를 쓸 때 나오는 에러가 두 종류로 갈리는데, 모양이 완전히 달라서 처음 보면 당황합니다. 실제로 돌려 봤습니다.
첫째, 키가 아예 없을 때입니다. 재밌는 건 anthropic.Anthropic()을 만드는 시점에는 아무 일도 안 일어난다는 겁니다. 객체는 멀쩡히 만들어지고 api_key가 None인 채로 있다가, 첫 요청을 보낼 때 터집니다. 게다가 인증 에러가 아니라 TypeError입니다.
TypeError: Could not resolve authentication method.
Expected one of api_key, auth_token, or credentials to be set.둘째, 키는 있는데 틀린 경우입니다. 이때는 서버까지 갔다 오므로 anthropic.AuthenticationError가 나고 status_code는 401입니다.
import anthropic
client = anthropic.Anthropic()
try:
client.models.list()
except TypeError as e:
print("키가 아예 안 잡혔습니다:", e)
except anthropic.AuthenticationError as e:
print("키가 틀렸습니다:", e.status_code) # 401TypeError가 나왔다면 서버는 구경도 못 한 겁니다. 환경변수가 안 잡힌 것이니 키를 다시 발급받지 말고 터미널부터 새로 여세요.
키만 만들면 요금이 나가나
Claude API 요금은 주고받은 토큰 양으로 매겨집니다. 2026년 9월 6일 기준 공식 가격표에서 자주 쓰는 모델만 옮기면 이렇습니다. (백만 토큰당, 미국 달러)
| 모델 | 입력 | 출력 |
|---|---|---|
| Claude Opus 5 | $5 | $25 |
| Claude Sonnet 5 | $2 | $10 |
| Claude Haiku 4.5 | $1 | $5 |
모델을 어떻게 고를지는 클로드 오퍼스 5 가격·성능 비교에 정리해 뒀습니다. 테스트 단계라면 Haiku로 붙여 보고 필요할 때 올리는 쪽이 안전합니다.
겁이 난다면 지출 한도를 직접 걸어 두는 것을 권합니다. 콘솔의 Billing 화면에서 내 티어 상한보다 낮은 값으로 한도를 정할 수 있고, 거기에 닿으면 요청이 에러로 막힙니다. 참고로 티어별 월 지출 상한은 Start $500 · Build $1,000 · Scale $200,000이고, 조직은 사용 이력과 계정 상태에 따라 자동으로 티어가 배정됩니다. 신규 조직은 표준 한도보다 낮은 Evaluation 티어에서 시작할 수 있고, 사용 이력이 쌓이면 자동으로 올라갑니다.
자주 묻는 질문 (FAQ)
Q. 키를 잃어버렸는데 다시 볼 방법이 정말 없나요?
없습니다. 콘솔은 생성 시점에 한 번만 전체 키를 보여 줍니다. 관리자용 Admin API에도 키 조회 기능이 있지만 비밀 값은 절대 돌려주지 않고 일부만 가린 힌트만 줍니다. 새 키를 만드세요.
Q. x-api-key와 Authorization: Bearer 중 뭘 써야 하나요?
둘 다 통합니다. 직접 확인해 봤는데, 일부러 틀린 키를 Authorization: Bearer로 보내도 "형식이 잘못됐다"가 아니라 키 자체를 검증한 결과가 돌아왔습니다. 다만 헤더를 아예 안 보내면 x-api-key header is required라고 안내하니, 처음 붙이는 거라면 x-api-key를 쓰는 편이 문서·에러 메시지와 결이 맞습니다.
Q. 워크스페이스를 여러 개 쓰는데 자꾸 엉뚱한 데로 붙습니다.
키가 여러 워크스페이스에서 통하는 경우에는 요청마다 anthropic-workspace-id 헤더도 같이 보내야 한다고 공식 문서가 명시합니다. 키만 넣고 이 헤더를 빼면 의도한 워크스페이스로 안 갈 수 있습니다.
Q. 만료 기한을 잘못 잡았습니다. 늘릴 수 있나요?
없습니다. 만료는 생성 시점에만 정해지고 나중에 변경할 수 없습니다. 새 키를 원하는 기한으로 만들어 갈아 끼우세요.
마무리
정리하면 Settings → API keys → Create key, 그리고 그 자리에서 전체 키를 복사해 두는 것 — 이 두 가지가 전부입니다. 나머지 사고는 대부분 키가 아니라 주변에서 납니다. 만료 기한을 짧게 잡아 놓고 잊었거나, 윈도우에서 setx 후 터미널을 새로 안 열었거나, 402·403처럼 키와 무관한 코드를 보고 키를 다시 발급받고 있거나입니다.
키를 만들었다면 위의 GET /v1/models 한 줄로 먼저 살아 있는지 확인하고, 지출 한도를 낮게 걸어 둔 다음에 코드를 붙이세요. 모델 목록과 가격은 바뀌니 실제 값은 콘솔과 공식 가격 문서에서 다시 확인하시길 권합니다.
📚 참고 출처 (2026년 9월 6일 확인)
· Claude Docs — Get your Claude API key
· Claude Docs — Authentication
· Claude Docs — Claude API errors
· Claude Docs — Rate limits
· Claude Docs — Pricing
COMMENTS