API 키 관리, 환경변수에 두는 법과 다른 기기로 옮겨도 되는 것·안 되는 것

2026-10-22

이 게시물은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

제미나이든 유튜브 데이터 API든, 키를 발급받은 직후에 하는 일은 대개 같습니다. 화면에 뜬 긴 문자열을 복사해서 코드 어딘가에 붙여 넣고, 돌아가는지 먼저 봅니다.

문제는 그다음입니다. 그 키가 코드 안에, 메신저 대화방에, 메모 앱에 그대로 남습니다. API 키 관리는 거창한 보안 솔루션 이야기가 아니라, 키를 어디에 두고 어디로는 보내지 않을지를 처음에 정하는 일입니다.

이 글은 발급 뒤 첫 할 일, 환경변수에 두는 세 가지 길, 다른 기기로 옮겨도 되는 것과 안 되는 것, 새 나갔을 때 순서를 적었습니다.

1. API 키 발급 뒤 첫 할 일, 코드 밖으로

▲ 키는 코드가 아니라 실행 환경에 두는 것이 기본입니다

API 키 발급 화면은 한 번만 전체 키를 보여 주는 곳이 많습니다. 닫으면 다시 못 보는 서비스도 있어 급하게 코드에 붙이게 됩니다.

그래도 코드 안에 직접 적는 것은 피합니다. 코드는 깃에 올라가고, 압축해서 보내고, 화면 공유에 찍힙니다. 키가 코드에 있으면 그 모든 길로 같이 갑니다.

키는 환경변수로: 코드에서는 `GEMINI_API_KEY` 같은 이름만 읽습니다
키 값은 .env 나 운영체제 설정에: 코드 저장소 밖에 둡니다
.gitignore 에 .env 를 먼저 적습니다. 커밋하고 나서 지우면 기록에 남습니다

발급 화면에서 복사한 키는 붙여 넣은 뒤 클립보드에서 지웁니다. Win+V 기록에 남아 있는 키를 다음 날 다른 데 붙이는 일이 흔합니다.

2. 환경변수 설정, 윈도우·맥·.env 세 가지

▲ 어디서 실행하느냐에 따라 자리가 다릅니다. 셋을 섞어 쓰면 어느 값이 읽히는지 헷갈립니다

환경변수 설정은 운영체제마다 자리가 다르고, 프로젝트 단위로 두는 .env 파일 방식이 따로 있습니다.

윈도우: 시작 메뉴에서 "환경 변수"를 검색해 시스템 속성 → 환경 변수 → 사용자 변수에 추가합니다. 열려 있던 터미널은 닫고 다시 열어야 읽습니다. 터미널에서만 쓸 거면 `setx 이름 값` 한 줄로도 됩니다
맥·리눅스: 홈 폴더의 `.zshrc` 나 `.bashrc` 끝에 `export 이름=값` 을 적고 터미널을 다시 엽니다. 이 파일은 셸이 켜질 때마다 읽습니다
.env 파일: 프로젝트 폴더에 `이름=값` 한 줄씩. 파이썬은 python-dotenv, 노드는 dotenv 패키지가 읽어 줍니다. 저장소에는 값이 빈 `.env.example` 만 올립니다

세 자리 중 한 곳만 쓰는 것이 관리의 절반입니다. 같은 이름이 운영체제와 .env 양쪽에 있으면 어느 쪽이 이기는지 라이브러리마다 달라서, 키를 바꿨는데 옛 키가 계속 쓰이는 일이 생깁니다.

서버에 올릴 때는 호스팅 서비스의 환경변수 화면이나 시크릿 매니저가 같은 역할을 합니다. 코드는 그대로 두고 값만 거기에 넣습니다.

3. 옮기지 말아야 할 것과 옮겨도 되는 것

▲ 비밀인지 아닌지로 가릅니다. 길이나 모양이 아닙니다

API 키 보관에서 사고가 나는 자리는 대개 "옮기는 순간"입니다. 노트북에서 받은 키를 데스크톱에 넣어야 해서, 집 PC에서 회사 PC로, 동료에게.

옮기지 말아야 할 것. API 키, 액세스 토큰, 시크릿, 비밀번호, 서비스 계정 JSON 파일. 이것들은 그 자체가 자격입니다. 메신저로 보내면 대화방 서버와 상대 기기에 남고, 메일로 보내면 받은편지함에 남습니다.

이 부류는 처음부터 각 기기에서 따로 발급하는 것이 맞습니다. 키 발급 화면은 몇 번이고 다시 열 수 있고, 기기별로 키가 다르면 하나가 새도 그것만 폐기하면 됩니다. 꼭 한 값을 공유해야 하면 팀의 비밀번호 관리자나 시크릿 매니저를 씁니다.

옮겨도 되는 것. 환경변수의 이름, 엔드포인트 주소, 모델 이름, 설치 명령어 한 줄, 설정 파일 중 값이 빠진 뼈대. 이것들은 공개 문서에도 적혀 있는 것들이고, 새 기기에서 환경을 맞출 때 가장 자주 옮기는 글입니다.

이런 공개 설정값을 폰에서 보고 PC에 치려면 글자가 많습니다. 자고투(ZAGO.TO)에 붙여 넣으면 1234 같은 숫자 4개가 나오고, 다른 기기 브라우저에서 zago.to 에 그 숫자를 넣으면 글이 그대로 떠서 복사하면 됩니다. 로그인도 설치도 없고, 빈 번호가 없을 때만 다섯 자리가 나옵니다.

다만 키는 자고투로도 안 됩니다. 브라우저에서 글을 가려 보내는 기능이 아직 없어서 서버가 지나가는 글을 읽을 수 있습니다. 공개 설정값은 괜찮지만 키·토큰·비밀번호는 넣지 마시라고 처음부터 적어 두는 이유입니다. 열지 않으면 1분, 연 뒤 1분이면 지워지고 다시 열 수 없으며, 파일은 옮기지 않고 글만 10,000자까지입니다.

공개키처럼 "공개"가 이름에 붙은 것은 옮겨도 됩니다. ssh 공개키를 다른 기기로 옮겨 서버에 등록하는 순서는 ssh-copy-id 윈도우에서 안 될 때, ssh 공개키를 복사해 서버에 등록하는 법에 따로 적었습니다.

저장소 주소를 옮기는 일은 깃허브 주소, 찾고 복사하고 다른 기기로 옮기기까지에 있습니다.

4. 키가 새 나갔다면, 순서는 폐기부터

API 키 유출은 깃에 올린 .env, 화면 공유에 찍힌 터미널, 메신저에 보낸 키 중 하나에서 시작합니다. 어디서 샜는지 찾는 일보다 먼저 할 일은 폐기입니다.

발급 화면에서 그 키를 삭제하거나 비활성화합니다. 새 키는 그다음에 만듭니다
새 키를 환경변수 자리에만 넣습니다. 1번과 2번에서 정한 그 한 곳입니다
깃에 올라갔다면 커밋을 지우는 것으로 끝나지 않습니다. 기록에 남고 이미 복제된 저장소에도 남습니다. 폐기한 키라서 괜찮다고 보고, 기록 정리는 그다음에 합니다
사용량 화면을 며칠 봅니다. 폐기 전 쓰인 양이 있으면 요금과 한도에 반영됩니다

대부분의 API 서비스는 키에 사용 한도와 허용 도메인·IP 를 걸 수 있습니다. 발급할 때 같이 걸어 두면 새 나가도 피해가 그 범위에서 멈춥니다.

한 줄 결론

API 키 관리는 발급 직후 키를 코드 밖 한 곳(환경변수나 .env)에 두고, 기기가 바뀌면 옮기지 않고 새로 발급하며, 공개 설정값만 자고투의 숫자 4개로 옮기는 것으로 끝납니다. 긴 글, 숫자 4개로.