OpenAI API 키 보안 설정: .env Git 제외 확인과 유출 시 키 교체 순서

프로젝트별 키 발급과 보관 위치

OpenAI Platform에서 사용할 프로젝트를 선택하고, 해당 프로젝트의 API keys 설정에서 키를 만듭니다. 프로젝트 구성원은 권한 범위 안에서 키를 만들 수 있으므로, 조직 관리자만 키를 발급할 수 있다는 설명은 맞지 않습니다. 실제 버튼과 권한은 현재 계정의 프로젝트 설정에서 확인합니다.

개인 개발용 키를 팀 공용 비밀값으로 공유하지 않습니다. 배포 환경에는 프로젝트에 맞는 서비스 계정이나 별도 키를 사용하고, 필요한 엔드포인트 권한만 부여합니다. ChatGPT 구독과 개발자 API의 결제·사용량은 별도로 관리되므로 각각 확인해야 합니다.

실행 위치별 키 보관 위치와 피해야 할 구성을 정리한 표입니다.

환경 변수를 사용한다고 해서 자동으로 안전해지지는 않습니다. 프런트엔드 빌드 도구가 공개 변수로 취급하는 이름을 쓰면 키가 번들에 포함될 수 있습니다. 아래 확인 예제는 키를 읽는 서버 프로세스를 대상으로 합니다.

.env 파일의 Git 추적 여부 확인

프로젝트 루트의 .gitignore에 다음 줄을 추가합니다. 예시 파일에는 변수 이름만 남기고 실제 값은 넣지 않습니다.

.env
.env.*
!.env.example

.env에는 OPENAI_API_KEY= 오른쪽에 발급받은 값을 저장합니다. 키를 명령줄 인수나 채팅에 붙여 넣지 않습니다. 다음 명령은 파일 이름과 제외 규칙만 확인하며 비밀값을 출력하지 않습니다.

git check-ignore -v .env
git ls-files -- .env

첫 명령에 제외 규칙이 표시되고 두 번째 명령의 출력이 비어 있으면 현재 .env는 Git 추적 대상이 아닙니다. 두 번째 명령에 .env가 표시되면 이미 추적 중이므로 .gitignore 추가만으로는 해결되지 않습니다.

로컬 파일을 남기고 추적만 해제하려면 git rm --cached -- .env를 실행하고 변경을 커밋합니다. 이전 커밋에 들어간 값은 이 명령으로 지워지지 않으므로, 노출 여부를 별도로 판단해야 합니다.

키 값을 출력하지 않는 환경 변수 로딩 검사

다음 예제는 Python 표준 라이브러리만 사용하며, 셸이나 실행 도구가 환경 변수를 주입한 프로세스에서 실행합니다. .env 파일을 만들었다고 Python이 자동으로 읽지는 않으므로, 사용하는 실행 도구의 환경 파일 로딩 설정을 먼저 적용해야 합니다.

import os

key = os.environ.get("OPENAI_API_KEY", "").strip()
if not key:
    raise SystemExit("OPENAI_API_KEY is missing")
print("OPENAI_API_KEY is configured; value hidden")

설정이 완료되면 OPENAI_API_KEY is configured; value hidden이 출력됩니다. 이 검사는 값의 존재만 확인하며, 키의 유효성, 결제 가능 여부, 모델 접근 권한은 검증하지 않습니다. 실제 API 연결 시험은 별도 단계이며, 모델 요청에는 비용이 발생할 수 있습니다.

검사 결과별 의미와 다음 확인 항목을 정리한 표입니다.

환경 변수 이름의 대소문자 처리는 운영체제마다 다르므로, 코드와 실행 환경 모두에서 OPENAI_API_KEY로 정확히 맞춰야 합니다.

지출 한도의 알림 전용과 강제 차단

공식 문서 기준으로 프로젝트 지출 한도는 두 가지 방식으로 설정할 수 있습니다. 알림 전용은 지출을 감시만 하고, 강제 한도(hard limit)는 추적된 지출이 한도에 도달한 뒤의 요청을 실패시킵니다. 따라서 설정 방식을 확인하지 않은 채 한도를 넘으면 자동으로 차단된다고 가정해서는 안 됩니다.

비용을 제한해야 하는 앱은 자체 서버에서 사용자별 요청 수, 동시 요청 수, 작업별 최대 출력, 일일 지출 추정치를 검사해야 합니다. 예를 들어 하루 작업을 100회로 제한한다면 101번째 작업은 API로 보내기 전에 자체 서버가 거절하도록 설계합니다.

서버가 여러 대라면 같은 카운터를 공유해야 합니다. 요청 수 한도는 금액 한도와 다르며, 긴 입력·출력이나 추가 기능 비용까지 막지는 못합니다.

키 유출 시 교체 절차와 정정 기록

노출이 의심되면 해당 키를 폐기하고 사용량을 확인합니다. 새 키를 발급한 뒤 서버의 비밀값을 갱신하고 서비스를 재시작하거나 재배포하며, 구 키를 사용하는 다른 배치 작업도 찾아 교체합니다. 계획된 교체에서는 구 키를 잠시 유지할 수 있지만, 실제 유출 사고에서는 서비스 연속성보다 악용 차단을 우선해야 합니다.

새 키 생성과 기존 키 폐기는 별도 작업입니다. 환경 변수 이름을 바꾸는 것만으로는 유출된 키가 무효화되지 않습니다. 로그·커밋 이력·공유 파일에 남은 값도 조사해야 하지만, 삭제 작업이 키 폐기를 대신하지는 않습니다.

발급부터 연결 확인까지의 절차

1. OpenAI Platform 화면에서 프로젝트를 선택하고 해당 프로젝트의 API keys 설정 메뉴를 엽니다.
2. 키를 만들고 화면에 표시된 값을 그 자리에서 .env 파일에 저장합니다.
3. .gitignore에 제외 규칙을 입력하고 git check-ignore -v .env 명령으로 제외 여부를 확인합니다.
4. 셸이나 실행 도구가 환경 변수를 주입한 상태에서 위 예제를 실행해 configured 출력을 확인합니다.
5. 실제 엔드포인트로 요청을 한 번 보내 인증까지 통과하는지 확인합니다.

git ls-files -- .env에 파일이 표시되는 경우에는 .gitignore 추가만으로 부족하므로 git rm --cached -- .env로 추적을 제외하고 커밋합니다. 이전 커밋에 값이 들어간 경우에는 노출로 판단해 키를 폐기합니다. 브라우저나 모바일 앱에서 호출하는 경우에는 키를 클라이언트에 보관하지 않고 자체 서버를 사용해야 합니다.

missing이 표시되면 값이 프로세스에 전달되지 않은 것이므로 실행 도구의 환경 파일 설정, 재시작 여부, 변수 이름을 차례로 확인합니다. configured인데 인증이 실패하면 폐기된 키인지, 다른 프로젝트의 키인지 확인합니다. 요청 제한 오류가 표시되면 대시보드의 사용량을 확인하고, 조직 계정에서 한도를 바꿀 수 없는 경우에는 관리자에게 프로젝트별 한도 조정을 요청합니다.

2026-09-08 정정: 이전 글의 ‘키 최대 5개’, ‘재발급 시 이전 키 자동 무효화’, ‘프로젝트 예산 초과 시 호출 거부’ 설명을 제거했습니다(2026-09-24 보완: 공식 문서에 강제 한도 옵션이 있어 알림 전용·강제 차단 선택으로 다시 적음). 비밀값을 화면에 출력하는 예제를 값의 존재만 검사하는 코드로 교체했습니다.