API 키 저장 방법: 환경변수 사용법

API 키를 코드와 공개 저장소에 노출하지 않고 환경변수로 관리하는 방법을 설명합니다. 로컬·배포 설정과 노출 시 대응 순서도 정리했습니다.

API 키 저장 방법의 기본은 브라우저 코드와 Git 기록에서 비밀값을 분리하고 서버 환경변수로 주입하는 것입니다.

연재 안내: 27편 전체 순서와 현재 공개된 글은 비개발자 바이브코딩 로드맵에서 확인할 수 있습니다.

파일 역할이 아직 섞여 있다면 먼저 초보 프로젝트 폴더 구조를 확인하세요.

Table of Contents

한 줄 답변

API 키는 소스 코드나 브라우저 화면에 직접 적지 않고 로컬에서는 .env, 배포 환경에서는 서비스의 환경변수 설정에 저장해야 합니다. 한 번 공개된 키는 코드에서 삭제하는 것만으로 안전해지지 않으므로 즉시 폐기하고 새로 발급해야 합니다.

API 키는 왜 비밀일까

API 키는 외부 서비스가 요청한 사용자를 식별하고 사용량과 비용을 연결하는 출입증입니다. 다른 사람이 키를 얻으면 내 계정으로 API를 호출해 요금을 발생시키거나 허용된 데이터에 접근할 수 있습니다.

비밀번호처럼 보이지 않는 긴 문자열이라도 공개 저장소, 화면 소스, 오류 로그, 스크린샷에 들어가면 노출입니다. 무료 API도 호출 제한을 소진하거나 서비스가 차단될 수 있으므로 같은 기준으로 관리합니다.

코드에 직접 적으면 생기는 문제

다음처럼 키를 코드에 쓰면 파일을 공유하거나 GitHub에 올리는 순간 함께 공개될 수 있습니다.

const apiKey = "실제-비밀키";

특히 프론트엔드 코드는 브라우저로 전달되므로 변수 이름을 바꾸거나 빌드 파일에 숨겨도 사용자가 확인할 수 있습니다. 비밀키가 필요한 외부 요청은 서버에서 처리하고 화면은 내 서버 API만 호출하도록 구성해야 합니다.

로컬에서는 .env로 분리한다

프로젝트 루트의 .env 파일에 비밀값을 넣고 코드에서는 환경변수 이름으로 읽습니다. 프레임워크마다 읽는 문법과 공개 변수 접두사가 다르므로 현재 공식 문서를 확인해야 합니다.

SERVICE_API_KEY=실제-비밀키

.env는 Git이 추적하지 않도록 .gitignore에 포함합니다. 공유가 필요한 경우에는 값 없이 변수 이름만 적은 .env.example을 만듭니다.

SERVICE_API_KEY=
DATABASE_URL=

이 파일은 새 환경에서 무엇을 설정해야 하는지 알려주는 목록이지 비밀값 보관소가 아닙니다.

배포 서비스에는 다시 등록한다

내 컴퓨터의 .env는 배포 서버에 자동으로 전달되지 않는 경우가 많습니다. Vercel, Netlify, 클라우드 서버 등 사용하는 배포 서비스의 프로젝트 설정에서 같은 변수 이름과 값을 등록해야 합니다.

개발, 미리보기, 운영 환경의 값을 구분할 수 있다면 운영 키를 개발에 재사용하지 않는 편이 안전합니다. 값을 바꾼 뒤에는 새 빌드나 재배포가 필요한지도 확인하세요.

Git에 올라가지 않았는지 확인한다

.gitignore에 추가하기 전에 이미 커밋한 파일은 추적 기록에 남을 수 있습니다. 현재 파일에서 지웠다고 과거 커밋까지 사라지는 것은 아닙니다. 저장소 검색과 Git 기록을 확인하고, 노출 가능성이 있다면 키를 교체합니다.

키 이름과 실제 값을 오류 메시지에 함께 출력하는 로그도 피합니다. 화면에는 일반적인 실패 안내만 보여주고 상세 오류는 접근이 제한된 서버 로그에서 확인합니다.

키가 노출됐을 때 대응 순서

해당 서비스 관리 화면에서 키를 즉시 비활성화하거나 삭제한다.
새 키를 발급한다.
로컬과 배포 환경변수를 새 값으로 바꾼다.
최근 사용량과 비정상 호출을 확인한다.
코드, Git 기록, 로그, 문서에서 노출 경로를 제거한다.
필요한 경우 서비스 제공자와 보안 담당자에게 알린다.

“코드에서 지웠으니 괜찮다”는 판단이 가장 위험합니다. 이미 복사된 비밀은 되돌릴 수 없으므로 키 자체를 교체해야 합니다.

배포 전 체크리스트

소스 코드에 실제 API 키 문자열이 없다.
.env가 .gitignore에 포함되어 있다.
프론트엔드 공개 변수에 비밀키를 넣지 않았다.
배포 서비스에 필요한 환경변수를 등록했다.
개발 키와 운영 키를 가능한 범위에서 분리했다.
사용량 제한과 비용 알림을 설정했다.

비밀정보 관리의 상세 기준은 OWASP Secrets Management Cheat Sheet 같은 보안 지침과 사용 중인 서비스의 공식 문서를 함께 확인하세요.

환경변수 이름만으로도 정보가 드러날 수 있다

값을 숨겼더라도 PRODUCTION_CUSTOMER_DB_PASSWORD처럼 이름이 시스템 구조와 중요 자산을 지나치게 설명할 수 있습니다. 변수 이름은 역할을 알아볼 수 있을 정도로 짓되 실제 고객명, 내부 서버 주소, 계정 정보를 넣지 않습니다.

환경변수를 사용할 수 있는 사람과 배포 서비스 권한도 점검하세요. 팀원이 모두 운영 비밀값을 볼 필요는 없습니다. 개발, 미리보기, 운영 환경의 접근 권한과 키를 분리하고 퇴사자·외부 협력자의 권한을 회수합니다.

키 교체 주기와 담당자, 비상 폐기 방법도 문서에 남깁니다. 환경변수에 넣었다는 사실만으로 관리가 끝나는 것이 아니라 생성부터 저장, 사용, 교체, 폐기까지의 수명주기를 관리해야 합니다.

개발을 멈춘 테스트 프로젝트의 키도 정리 대상입니다. 더 이상 사용하지 않는 키와 서비스 계정은 비활성화하고, 어떤 배포가 어떤 키를 사용하는지 목록으로 연결하세요. 키가 많아질수록 이름만 보고 임의로 삭제하지 말고 실제 호출과 배포 설정을 확인합니다. 정기 점검 날짜를 정해 오래된 키, 과도한 권한, 소유자를 알 수 없는 값을 함께 정리하면 노출 위험과 운영 혼란을 줄일 수 있습니다.

API 키 저장 방법 최종 점검

API 키 저장 방법을 점검할 때는 .env 파일이 Git 제외 목록에 있는지만 보지 말고 빌드 산출물, 브라우저 네트워크 응답, 로그에도 값이 남지 않는지 확인하세요. API 키 저장 방법이 올바르더라도 프론트엔드 코드에서 직접 사용하면 사용자에게 노출될 수 있습니다.

이미 커밋하거나 공유했다면 문자열을 지우는 것만으로 끝내지 말고 해당 키를 즉시 폐기하고 새 키를 발급하세요. 사용 기록과 비용을 확인하고 저장소 기록 정리가 필요한지도 서비스 운영자와 함께 판단해야 합니다.

환경변수를 준비했는데 설치나 실행 단계에서 막힌다면 다음 글인 npm install 오류: 앱이 안 켜질 때에서 현재 폴더, Node 버전, 첫 오류 메시지를 확인하는 순서를 따라가세요.

바이브코딩 전체 순서 보기

바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.