마지막 수정

API 키를 안전하게 관리하는 기본 원칙

개인 프로젝트와 정적 블로그 운영에서 API 키와 토큰을 코드·Git·배포 환경에 안전하게 분리해 관리하는 기준을 기록했습니다.

개발 자동화 #API 키#보안#개인 프로젝트

API 키 관리는 재미없는 주제입니다. 그런데 한 번만 실수해도 제일 피곤한 주제이기도 합니다. 블로그 운영 자동화나 배포 설정을 만질 때마다 이 부분이 계속 걸렸습니다.

Daejin Lab에는 아직 복잡한 서버 기능이 많지 않지만, 앞으로 분석 도구나 외부 API를 붙이면 키를 다루게 됩니다. 그래서 기능을 붙이기 전에 먼저 “절대 글이나 저장소에 섞이면 안 되는 것”부터 정리했습니다.

API 키는 코드에 직접 쓰지 않는다

가장 기본은 코드 안에 키를 직접 넣지 않는 것입니다.

나쁜 예:

const apiKey = "sk-...";

좋은 방향:

const apiKey = readFromEnvironment("API_KEY");

실제 값은 로컬 환경 변수 파일이나 서비스의 환경 변수 설정에 둡니다.

API 키 신뢰 경계

이 카드는 코드 분리 → 환경 분리 → 배포 Secret → 전환 전 재검증 흐름입니다.

로컬 비밀 설정 파일은 Git에 올리지 않는다

환경 변수 파일에는 민감한 값이 들어갑니다. 그래서 Git에서 제외하는 규칙을 먼저 넣어두는 편이 안전합니다.

예:

local-secret-file
local-secret-file.*
*.local-secret
.secrets/

처음 프로젝트를 만들 때 이 설정을 먼저 해두면 실수 가능성이 줄어듭니다.

공개 저장소 전환 전 확인할 것

처음에는 private 저장소로 시작하더라도, 나중에 public으로 바꿀 수 있습니다. 전환 전에는 최소한 다음을 확인해야 합니다.

  • 로컬 환경 변수 파일이 커밋되지 않았는지
  • 토큰이나 비밀번호가 코드에 남아 있지 않은지
  • README에 개인 정보가 들어가지 않았는지
  • 테스트용 계정 정보가 남아 있지 않은지
  • Git 이력에 민감정보가 들어간 적은 없는지

한 번 Git 이력에 들어간 키는 삭제해도 안전하다고 보기 어렵습니다. 그 경우 키를 폐기하고 새로 발급하는 편이 안전합니다.

서비스별 환경 변수 사용

배포 서비스에서는 보통 환경 변수를 따로 설정할 수 있습니다.

  • Cloudflare Pages: 프로젝트 설정의 환경 변수
  • Vercel: Project Settings의 Environment Variables
  • GitHub Actions: Repository Secrets

서비스마다 이름은 다르지만 원칙은 같습니다. 코드는 값을 읽기만 하고, 실제 비밀값은 배포 서비스에 저장합니다.

Daejin Lab에서 적용한 보안 기준

이 블로그 프로젝트에서도 처음부터 민감정보를 커밋하지 않는 것을 원칙으로 잡았습니다.

프로젝트 공통 규칙에는 아래 항목을 두었습니다.

local-secret-file
local-secret-file.*
*.local-secret
.secrets/

그리고 실제 Google Search Console 인증 태그를 넣을 때도 API 토큰과 구분해서 판단했습니다. Search Console의 HTML 메타 태그는 공개 HTML에 들어가는 검증용 값이지만, GitHub 토큰이나 Cloudflare API 키는 절대 코드에 넣으면 안 됩니다.

구분 기준은 이렇게 잡았습니다.

공개 HTML에 들어가는 검증 메타 태그: 공개 가능
GitHub token: 공개 금지
Cloudflare API token: 공개 금지
Google OAuth client secret: 공개 금지
AdSense 결제/계정 정보: 공개 금지
로컬 환경 변수 파일: 공개 금지

GitHub 인증 문제에서 배운 점

이번 프로젝트에서는 GitHub HTTPS 인증이 자동화 세션에서 잘 되지 않아 SSH 키 방식으로 바꿨습니다.

중요한 점은 비밀키를 외부에 공유하지 않고, 공개키만 GitHub에 등록했다는 것입니다.

공개키: GitHub에 등록 가능
비밀키: 로컬에만 보관

이 구분은 API 키 관리와도 비슷합니다. 남에게 보여도 되는 값과 절대 보여주면 안 되는 값을 먼저 나누는 습관이 중요합니다.

공개 전 점검 명령

나중에 저장소를 public으로 바꾸기 전에는 최소한 아래처럼 민감한 문자열 후보를 검색할 예정입니다.

git status --short
git log --oneline

그리고 파일 내용에서는 API_KEY, TOKEN, SECRET, 로컬 환경 변수 파일 이름 같은 단어가 실수로 들어갔는지 확인해야 합니다. 실제 키가 한 번이라도 Git 이력에 들어갔다면 삭제만으로는 부족하고, 해당 키를 폐기한 뒤 새로 발급하는 편이 안전합니다.

블로그 운영과 연결되는 부분

API 키 관리는 개발 글쓰기 방식과도 연결됩니다. 블로그에 문제 해결 과정을 남기다 보면 명령어, 설정 화면, 배포 서비스 이름을 적게 되는데, 이때 공개 가능한 정보와 비공개 정보를 계속 나눠야 합니다.

Daejin Lab에서는 아래처럼 선을 나눴습니다.

공개해도 되는 것: 사용한 스택, 빌드 명령, 공개 URL, 검증용 HTML 메타 태그
공개하면 안 되는 것: API token, OAuth secret, 개인 계정 정보, 로컬 환경 변수 파일 내용, 비밀 SSH 키

그래서 발행 버튼을 자동화하지 않기로 한 이유에서 적은 것처럼, 보안이 섞일 수 있는 글은 최종 공개 전에 사람이 다시 봐야 합니다. 배포 쪽은 Cloudflare Pages 배포 후 확인 체크리스트와 같이 두고, 작업 경계는 AI 에이전트에게 맡기기 좋은 일과 나쁜 일에서 다시 확인합니다.

이 기준이 있으면 공개 글에 “무엇을 했는지”는 남기면서도, 실제 접근 권한을 주는 값은 밖으로 내보내지 않을 수 있습니다.

지금 남긴 키 관리 기준

API 키 관리는 복잡한 보안 기술보다 기본 습관이 중요합니다. 코드에 직접 쓰지 않고, 로컬 환경 변수 파일을 Git에서 제외하고, 공개 전 이력을 확인하는 것만으로도 큰 사고를 줄일 수 있습니다.

특히 개인 블로그를 여러 개 운영할수록 “어떤 값은 공개 가능하고 어떤 값은 절대 공개하면 안 되는지”를 프로젝트마다 반복해서 확인해야 합니다.

제일 먼저 막아둘 것

API 키 관리는 멋진 보안 체계를 만드는 일보다, 실수할 경로를 줄이는 일에 가까웠습니다. 공개 글, 예제 코드, 커밋 로그에 키가 섞이지 않게 하는 것이 먼저입니다.

다음에 외부 서비스를 붙일 때는 기능 구현보다 로컬 환경 변수 파일, gitignore, 예제 파일, 배포 환경 변수부터 확인할 생각입니다. 키가 필요한 기능은 나중에도 만들 수 있지만, 노출된 키를 수습하는 일은 훨씬 귀찮습니다.

불안하면 자동화하지 않는다

API 키는 한 번 잘못 다루면 복구가 귀찮습니다. 그래서 저는 이 부분만큼은 속도를 포기하는 편이 낫다고 봅니다. 자동화가 편하더라도 키가 어디에 저장되는지 설명하지 못하면, 그 자동화는 아직 제 프로젝트에 넣지 않는 쪽으로 정했습니다.

공개 예시에서 보여줄 경계

API 키 글은 실제 화면을 보여주기 가장 위험한 주제입니다. 그래서 이 글을 보강할 때도 실제 키, 계정 화면, 환경 변수 원문은 쓰지 않기로 했습니다. 대신 공개 가능한 정보와 금지 정보를 먼저 나눴습니다.

공개 가능한 정보와 공개 금지 정보를 나눈 카드: 스택, 빌드 명령, 공개 URL은 가능하고 API token, OAuth secret, 비밀 SSH 키, 계정 화면은 금지

보안 글의 이미지는 실제 화면보다 재현용 카드가 안전합니다. 값이 아니라 경계만 보여주는 것이 목적입니다.

더미 예시로만 남기는 이유

예제 코드도 조심해야 합니다. 실제 키처럼 보이는 문자열을 넣으면, 읽는 사람에게도 나쁜 습관을 줄 수 있습니다. 그래서 공개 글에는 더미 이름만 남기는 편이 낫다고 봅니다.

더미 환경 변수 예시 카드: PUBLIC_SITE_URL, EXAMPLE_API_KEY, REAL_TOKEN은 글과 저장소에 쓰지 않음, 로컬 전용 환경 파일은 Git 제외

이 카드는 실제 환경 변수 값이 아닙니다. 공개 글에는 값이 아니라 보관 위치와 금지 기준만 남깁니다.

확인한 자료와 기록

이 글을 보강할 때 참고한 공식 문서는 아래입니다.

실수했을 때의 기준

API 키를 한 번 공개했다면, “파일에서 지웠다”로 끝내지 않는 쪽이 안전합니다. Git 이력, 배포 로그, 캐시, 복사본에 남아 있을 수 있기 때문입니다. 제 기준은 아래입니다.

실제 키가 노출됐다고 의심되면 폐기하고 재발급한다.
공개 글에는 키 값을 일부라도 쓰지 않는다.
예제는 값 없는 샘플 파일 형태로 둔다.
배포 서비스에는 환경 변수로 넣고, source repo에는 넣지 않는다.

이 기준은 겁을 주려는 게 아닙니다. 실수했을 때 되돌리는 비용이 크기 때문에, 처음부터 공개 가능한 정보만 글에 남기자는 뜻입니다.

자주 묻는 질문

Search Console 메타 태그나 AdSense publisher ID도 비밀인가요?

일반적인 API 토큰이나 password와는 성격이 다릅니다. 공개 HTML에 들어가도록 설계된 검증/게시자 값은 사이트에 보일 수 있습니다. 하지만 OAuth client secret, API 토큰, cookie, SSH 비공개 키는 공개하면 안 됩니다.

예제 코드에 가짜 키를 넣어도 되나요?

저는 실제 키처럼 보이는 긴 문자열도 피하는 편입니다. EXAMPLE_API_KEY, [REDACTED_DUMMY_VALUE]처럼 명확히 더미라고 보이는 형태가 안전합니다.

FAQ

API 키 예시는 실제 값으로 보여줘야 하나요?

아닙니다. 공개 글에서는 더미 값이나 구조만 보여주는 편이 안전합니다. 실제 키 형식과 길이를 그대로 노출하면 독자가 따라 하기 전에 운영자가 먼저 위험해질 수 있습니다.

환경 변수 파일은 git에 올리면 안 되나요?

실제 비밀값이 들어간 환경 변수 파일는 올리지 않는 것이 기본입니다. 공개 repo에는 예시 환경 변수 파일처럼 이름과 구조만 남기는 편이 안전합니다.

AdSense 준비와 API 키 관리가 무슨 관련이 있나요?

사이트 신뢰는 글 내용뿐 아니라 공개 안전에서도 나옵니다. 비밀값 관리 기준이 분명하면 자동화 블로그처럼 보이는 위험을 줄일 수 있습니다.