API 키

API 키는 프로그램이 API를 부를 때 "저 맞아요"라고 내미는 비밀 출입증이에요. 호텔 카드키처럼, 잃어버리면 주운 사람도 문을 열 수 있어서 바로 끄고 새로 받아야 해요.

글 서순명(솔리드그루 이사 · 퓨쳐인프라 운영) · 2026-10-29 작성 · 예시는 2026-10-29 Windows 11 에서 가짜 키·틀린 키로 직접 실행

API 키는 어떻게 동작하나요?

내 프로그램이 API에 요청을 보낼 때 머리말(헤더)에 키를 같이 실어요. 많은 서비스가 "Authorization: Bearer 키값" 모양을 써요.

서버는 키를 보고 세 가지를 판단해요. 등록된 키인지, 이 키에 허락된 일인지, 사용량을 어느 계정에 달지예요. 그래서 AI API처럼 쓴 만큼 돈이 나가는 서비스에서는 키가 곧 지갑이에요.

비밀번호·토큰과는 뭐가 달라요?

정리하면, 사람에겐 비밀번호, 프로그램에겐 API 키예요. 둘 다 남에게 보여 주면 안 되는 건 같아요.

API 키는 어떻게 발급받나요?

서비스마다 화면은 달라도 순서는 거의 같아요.

1. 서비스에 가입하고 콘솔(관리 화면)에 들어가요.
2. "API 키" 메뉴에서 새 키 만들기를 눌러요. 이름을 붙여 두면 나중에 어떤 앱 키인지 알아요.
3. 키가 화면에 나오면 바로 복사해요. 대부분 이때 한 번만 보여 줘요.
4. 복사한 키를 내 컴퓨터의 .env 파일에 붙여 넣어요.

퓨쳐인프라라면 콘솔 API 키 화면에서 만들어요. 키는 발급할 때 한 번만 보여 주고, 키마다 권한(스코프)과 월 한도를 따로 걸 수 있어요.

직접 해 보면 어떻게 나오나요?

2026-10-29 Windows 11 PC에서 직접 실행한 결과예요. 키는 일부러 틀린 값과 가짜 값(sk-test-…)만 썼어요. 먼저 퓨쳐인프라 API에 열쇠 없이, 그리고 틀린 열쇠로 불러 봤어요.

$ curl -s https://futureinfra.ai/v1/me   (열쇠 없이)
{"error":"not_authenticated"}  <- HTTP 401
$ curl -s -H "Authorization: Bearer pk_live_wrongkey123" https://futureinfra.ai/v1/me   (틀린 열쇠)
{"error":"invalid_api_key"}  <- HTTP 401

둘 다 401(인증 실패)이지만 이유가 달라요. 앞은 "열쇠가 없어요", 뒤는 "그런 열쇠는 없어요"예요. 앱이 401을 받으면 이 error 칸부터 보면 돼요. 다른 상태 번호는 REST API 글의 표에 있어요.

다음은 키를 저장소에서 빼고, 코드 밖에서 읽는 연습이에요.

$ cat .gitignore
.env
$ git add . && git status --short   (.env 가 빠지는지 확인)
A  .gitignore
A  use_key.py
$ git check-ignore -v .env
.gitignore:1:.env	.env
$ python use_key.py   (키 없이)
MY_API_KEY 가 없어요. .env 를 확인하세요
$ MY_API_KEY=$(grep MY_API_KEY .env | cut -d= -f2) python use_key.py
키를 읽었어요. 길이 26 / 앞 3글자 sk-…

• git add . 로 전부 담았는데도 목록에 .env 가 없어요. check-ignore 가 ".gitignore 1번째 줄 때문에 빠졌다"고 알려 줘요.
• use_key.py 코드에는 키가 한 글자도 없어요. 실행할 때 환경변수로 넘겨받아요.
• 확인용 출력도 키 전체 대신 길이와 앞 3글자만 찍었어요. 로그에 키가 남지 않게 하려는 거예요.

API 키는 어디에 보관해야 해요?

넷째 줄은 바이브코더가 자주 밟는 함정이에요. Vite는 VITE_ 로 시작하는 변수를 화면 코드에 넣고, 비밀값을 담지 말라고 공식 문서에 적어 뒀어요(Vite 문서). Next.js의 NEXT_PUBLIC_ 도 같은 방식이에요(Next.js 문서). AI 키는 서버 쪽 코드에서만 읽어요.

키가 새면 무엇부터 해야 해요?

깃허브는 공개 저장소를 무료로 자동 검사해서, 키처럼 보이는 값이 올라오면 알려 줘요. 이때 모든 브랜치의 전체 기록까지 봐요. 깃허브 문서도 새어 나간 키는 즉시 교체하라고 권해요. 키를 이미 폐기했다면 기록에서 지우는 수고는 대개 하지 않아도 된다고 해요(GitHub secret scanning).

자주 하는 오해와 주의할 점

• "커밋에서 지웠으니 끝났다" 지운 커밋 앞의 기록에 키가 그대로 남아요. 폐기가 먼저예요(깃허브 뜻 참고).
• "비공개 저장소라 괜찮다" 나중에 공개로 바꾸거나 협업자를 초대하면 같이 보여요. 비공개라도 .env 는 빼요.
• "키 하나로 다 쓰면 편하다" 앱마다 키를 나누면, 하나가 새도 그 앱 키만 끄면 돼요. 권한과 한도도 앱마다 좁게 걸어요.

바이브코딩으로 앱을 여러 개 만들수록 키도 늘어나요. 어떤 키를 어느 앱에 썼는지 이름으로 적어 두면 폐기할 때 헤매지 않아요.

퓨쳐인프라에서는 어떻게 하나요?

퓨쳐인프라 API 키는 "Authorization: Bearer pk_live_…" 모양으로 보내요. 발급 때 한 번만 보여 주고, 키마다 스코프와 월 한도를 걸 수 있어요. 앱 호스팅에 넣는 환경변수(비밀값)는 암호화해 보관하고 다시 보여 주지 않아요. 바꿀 땐 새 값으로 덮어써요.

AI 라우터를 쓰면 300종 넘는 AI 모델을 API 키 하나로 불러요(OpenAI 호환). 회사마다 키를 따로 받고 지킬 일이 줄어요. 쓴 만큼 충전 지갑에서 빠져나가요.

자주 묻는 질문

API 키를 잊어버리면 다시 볼 수 있어요?

대부분의 서비스는 발급할 때 한 번만 보여 주고 다시 보여 주지 않아요. 잃어버렸다면 그 키를 폐기하고 새 키를 만들면 돼요. 새 키를 .env 와 서버 설정에 넣으면 끝이에요.

API 키는 언제 바꾸는 게 좋아요?

새어 나간 게 의심될 때는 바로 바꿔요. 함께 일하던 사람이 팀을 떠날 때, 키를 메신저로 주고받았을 때도 바꾸는 게 안전해요. 정기적으로 바꾸는 규칙을 둔 회사도 많아요.

.env 파일은 어떻게 만들어요?

프로젝트 맨 위 폴더에 .env 라는 이름의 글자 파일을 만들고 'MY_API_KEY=키값'처럼 한 줄씩 적어요. 그다음 .gitignore 파일에 .env 한 줄을 넣어 저장소에 올라가지 않게 해요.

API 키를 팀원과 나눠 써도 돼요?

되도록 사람마다, 앱마다 따로 발급해요. 같은 키를 나눠 쓰면 누가 얼마나 썼는지 알 수 없고, 한 명이 실수하면 모두의 키를 바꿔야 해요.

관련 용어

• API는 API 키를 내밀고 부르는 창구예요.
• REST API는 401·403 같은 상태 번호가 정리된 글이에요.
• 깃허브 글에는 키가 자주 새는 곳과 비밀값 검사 기능이 나와요.
• JSON 글에는 설정 파일에 키를 적지 말아야 하는 이유가 있어요.
• OAuth는 키 대신 로그인으로 권한을 빌려주는 방식이에요.
• 클로드 코드는 키를 .env 로 다루게 부탁하는 AI 코딩 도구예요.