API 키를 안전하게 보관하기: 환경 변수, .gitignore, 유출 대응

키는 코드가 아니라 환경 변수에 두고, .env 파일은 .gitignore에 한 줄을 추가해 git에서 제외하세요. 키가 이미 공개된 곳에 노출되었다면, 먼저 키를 처리하고 그다음에 정리하세요. 키가 여전히 코드와 도구에 남아 있는 상태에서 git 기록을 정리해도 아무것도 해결되지 않습니다.

이게 전부입니다. 이 가이드는 실전 버전입니다(기본 개념은 What is an API key에 있습니다): 명령 세 개, 동작하는 요청 하나, 그리고 문제가 생겼을 때를 위한 짧은 계획입니다.

키가 코드에 있으면 안 되는 이유#

API 키는 당신의 돈을 쓰는 비밀번호입니다. 키를 가진 사람은 누구든 당신의 잔액으로 요청을 보낼 수 있고, 서비스는 그 사람과 당신을 구분할 수 없습니다.

문제가 생기는 흔한 경로는 지루할 정도로 뻔합니다. 첫 요청을 성공시키려고 스크립트에 키를 붙여넣고, 스크립트가 동작하고, git push를 하고, 저장소는 공개됩니다. 아니면 동료에게 설정 파일을 보냅니다. 아니면 구석에 키가 보이는 오류 화면을 캡처합니다. 매번 결과는 같습니다.

GitHub은 이 패턴을 잘 압니다. GitHub의 시크릿 스캐닝(GitHub 문서, 2026년 10월 29일 확인)은 모든 브랜치의 전체 Git 기록에서 하드코딩된 자격 증명을 찾고, 이슈, 풀 리퀘스트, 토론, 위키, 비밀 gist까지도 검사하며, 발견하면 경고를 띄웁니다. 즉 다음 커밋에서 그 줄을 지워도 아무것도 바뀌지 않습니다. 이전 커밋에 여전히 남아 있기 때문입니다.

다음은 같은 스크립트의 전과 후입니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key="<your-key>",  # pasted here: ends up in git
)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

두 번째 버전은 그대로 GitHub, 채팅, 코드 리뷰에 올릴 수 있습니다. 키는 파일 밖, 당신의 머신에 있습니다.

1단계: 키를 환경 변수에 넣기#

환경 변수는 터미널이 실행하는 모든 프로그램에 전달하는 이름 붙은 값입니다. 스크립트는 CHEAPTOKENS_API_KEY을 이름으로 요청하고, 값이 어디서 왔는지는 알지 못합니다.

macOS와 Linux에서:

export CHEAPTOKENS_API_KEY="<your-key>"

Windows PowerShell에서:

setx CHEAPTOKENS_API_KEY "<your-key>"

사람들이 자주 걸리는 두 가지가 있습니다. export은 해당 터미널 창에서만 유지되므로, 유지하려면 셸 프로필(~/.zshrc 또는 ~/.bashrc)에 줄을 추가하세요. 그리고 setx는 입력한 창을 바꾸지 않으므로, 테스트 전에 새 터미널을 여세요.

이제 전체 요청입니다. OpenAI 호환 엔드포인트 https://api.cheaptokens.dev/v1와 전체 id를 사용하는 DeepSeek-V4-Flash를 씁니다(deepseek-ai/DeepSeek-V4-Flash-0731; 제공자마다 이름이 다르므로 id는 CheapTokens 문서에서 가져오세요):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

짧은 인사는 대략 입력 20 토큰, 출력 20 토큰의 요청이며, 현재 가격으로 $0.0000023입니다(전체 목록은 가격 페이지에 있습니다). 아직 첫 요청을 보내지 않았다면 Your first API request with CheapTokens가 처음부터 안내합니다.

모델의 답은 choices[0].message.content로 돌아오고, usage는 계산된 토큰을 보여줍니다. 키는 파일에 절대 나타나지 않습니다.

2단계: 커밋하지 않고 .env 파일 사용하기#

새 창마다 export를 입력하는 건 지칩니다. .env 파일은 값을 프로젝트 옆 한 곳에 보관합니다:

CHEAPTOKENS_API_KEY=<your-key>

Python에서는 python-dotenv로 읽습니다(pip install python-dotenv):

from dotenv import load_dotenv
load_dotenv()  # fills os.environ from .env

이 파일은 git이 절대 보지 않아야 안전합니다. 첫 커밋 전에 .gitignore에 추가하세요:

echo ".env" >> .gitignore
git check-ignore -v .env

모든 게 제대로라면 두 번째 명령은 .gitignore:1:.env .env 같은 것을 출력합니다: git이 어떤 규칙으로 파일을 무시하는지 알려줍니다. 아무것도 출력하지 않으면 규칙이 동작하지 않는 것입니다. Windows에서는 편집기로 .gitignore를 만들어 .env 줄을 넣거나, Add-Content .gitignore .env를 사용하세요: PowerShell의 >>는 UTF-16으로 쓸 수 있어 git이 무시할 수 있습니다.

한 가지 함정: .gitignore는 git이 아직 추적하지 않는 파일에만 영향을 줍니다. .env가 이미 한 번 커밋되었다면 git rm --cached .env를 실행해 git이 추적을 멈추게 하고, 그 안의 키는 노출된 것으로 간주하세요(자세한 내용은 아래에). 깔끔한 습관은 값 대신 변수 이름과 자리 표시자를 담은 .env.example를 커밋해, 동료가 무엇을 설정해야 하는지 알게 하는 것입니다.

키가 유출되었다면: 순서대로 할 일#

키가 공개 저장소에 갔을 수도 있고, 스크린샷에 남았을 수도 있고, 설정 전체를 포럼 스레드에 붙여넣었을 수도 있습니다. 어떤 단계의 속도보다 순서가 더 중요합니다.

GitHub의 자체 안내(같은 페이지, 2026년 10월 29일 확인)는 자격 증명을 즉시 교체하라고 합니다. Git 기록 재작성은 선택 사항이며, 자격 증명이 폐기되면 대개 불필요합니다. 사람들은 보통 반대로 합니다: 키가 여전히 동작하는 동안 한 시간을 기록 정리에 씁니다. 그러지 마세요.

정리가 끝나면 1단계처럼 작은 테스트 요청을 하나 보내고 잔액을 확인하세요. 응답이 오고 잔액과 요청이 정상으로 보이면 정리가 끝난 것입니다. 며칠 동안 잔액을 지켜보세요. 한때 공개되었던 키는 코드에서 제거한 뒤에도 노출된 것으로 간주해야 하므로, 보내지 않은 요청이 있는지 잔액과 요청 수를 지켜보고, 그 키를 새 위치에서 재사용하지 마세요. 키가 흔히 있는 위치는 Where to plug in your own API key를 참고하세요.

스스로 점검하기#