AI 에이전트 API 키, 만료일만 넣으면 끝일까? 멈추지 않고 교체하는 6칸 rollout 계약

읽는 시간 약 8분 · AI 에이전트 운영

질문: 에이전트 worker가 쓰는 OpenAI project API key에 만료일을 걸었다면, 새 키를 언제 배포하고 어떤 증거를 본 뒤 이전 키를 폐기해야 할까요?

짧은 답: 만료일만 정하는 것으로 전환이 끝나지는 않습니다. worker별로 소유자·수명·교체 창·최소 요청 검증·cutover/복구·정적 key 축소의 여섯 칸을 채운 뒤, 새 자격증명에서의 실행 증거를 확인하고 이전 키를 폐기하는 순서가 필요합니다.

AI 에이전트 API key를 새 자격증명으로 교체하고 검증 후 이전 key를 폐기하는 흐름 — 자격증명 교체는 키 하나를 바꾸는 일이 아니라 worker 단위의 배포 순서를 확인하는 일입니다.

핵심 요약

새 key 생성과 이전 key 폐기는 같은 작업이 아닙니다. 새 key가 실제 worker에서 최소 요청을 통과한 뒤에야 폐기 판단을 할 수 있습니다.
전환의 단위는 조직 전체가 아니라 worker 하나입니다. 소유자, 환경, 되돌림 책임자가 다르면 같은 key를 공유해도 위험은 달라집니다.
정적 project key를 곧바로 없앨 필요는 없습니다. 전용 principal, 환경 분리, 정확한 claim 검증, 짧은 수명 토큰을 운영할 준비가 있을 때 workload identity를 검토합니다.
로그에는 key 값이 아니라 운영 증거만 남깁니다. 성공·오류·실행 시각·담당자·되돌림 여부처럼 전환 판단에 필요한 신호를 기록합니다.

왜 key rotation은 배포 사건일까요?

에이전트 worker는 단지 API를 한 번 호출하는 프로그램이 아닙니다. 작업 스케줄러, secret store, 실행 환경, 외부 도구, 오류 알림이 함께 움직입니다. 그래서 새 key를 만들었다는 사실만으로 기존 worker가 새 자격증명을 사용한다고 볼 수는 없습니다.

OpenAI의 Production best practices는 만료 전에 replacement를 만들고, 애플리케이션을 새 key로 전환한 뒤 작동을 확인하고 기존 key를 revoke하는 순서를 안내합니다. 이 순서는 무중단을 보장한다는 뜻이 아니라, 폐기 전에 검증할 기회를 남긴다는 운영 원칙으로 이해하는 편이 안전합니다.

비용·신뢰성 관점: 새 key가 연결되지 않은 상태에서 이전 key를 먼저 폐기하면, 실패한 재시도와 수동 복구에 시간이 듭니다. 반대로 두 key를 구분 없이 오래 병행하면 노출 범위와 추적 비용이 커집니다. 교체 창은 짧게, 근거는 분명하게 운영하는 것이 핵심입니다.

특히 agent-generated code가 실행 환경의 파일, credentials, network에 접근할 수 있다는 점은 별도 경계가 필요하다는 뜻입니다. OpenAI의 Sandbox security 가이드는 workload 격리, 환경 분리, 승인된 outbound endpoint 제한, 장기 자격증명의 안전한 보관을 권합니다. 여기서 key 교체의 목표는 ‘더 자주 바꾸기’가 아니라 노출되었을 때 영향 범위를 줄이고, 무엇이 어디에서 쓰였는지 설명할 수 있게 만들기입니다.

FLOWIT 6칸 credential-expiry rollout 계약

전환을 시작하기 전에 worker마다 아래 여섯 칸을 한 장에 적어 두세요. 빈 칸이 하나라도 있으면 자동 전환보다 보류가 낫습니다.

에이전트 worker API key rotation을 위한 6칸 운영 계약 — 여섯 칸은 보안 체크리스트가 아니라, 전환을 시작하고 멈출 기준을 함께 적는 운영 계약입니다.

worker별 6칸 카드

소유자: 이 worker의 업무 책임자와 장애 시 승인권자를 적습니다. ‘플랫폼 팀’처럼 넓은 명칭만으로는 부족합니다.
수명: 새 자격증명의 생성일·검토일·만료 정책을 정합니다. 실제 값이나 secret 경로는 문서와 로그에 적지 않습니다.
교체 창: staging과 production을 섞지 않고, 영향이 작은 시간과 관찰 기간을 정합니다.
최소 요청 검증: 읽기 전용이거나 부작용이 작은 작업 하나를 골라 성공·오류 신호를 확인합니다.
cutover·복구: 새 key가 실패하면 어떤 설정을 되돌릴지, 누가 중단을 선언할지 정합니다. 이전 key는 검증 중의 임시 복구 수단일 뿐입니다.
정적 key 축소: 다음 교체 전에 전용 principal 또는 workload identity로 옮길 수 있는지, 그 전제가 갖춰졌는지 기록합니다.

이 카드의 장점은 팀이 ‘키가 있나?’가 아니라 ‘이 worker는 전환해도 되는가?’를 논의하게 만든다는 데 있습니다. 예를 들어 야간 배치 worker에 소유자가 없고 오류 알림도 없다면, 새 key를 만들어도 이전 key 폐기는 승인할 수 없습니다.

정적 project key 유지, workload identity 검토, 전환 보류

모든 worker를 같은 방식으로 바꿀 필요는 없습니다. 다음 표는 오늘 어떤 선택이 가능한지 판단하는 데 쓰는 최소 기준입니다.

선택	진행해도 되는 조건	필요한 증거	하지 말아야 할 일
정적 project key 유지	worker 소유자와 환경이 분리되어 있고, 새 key 교체·검증·폐기 순서를 운영할 수 있습니다.	최소 요청 성공, 오류 확인, 복구 담당자, 이전 key 폐기 승인 기록	여러 worker가 같은 key를 쓰는데 사용처를 모른 채 폐기하지 않습니다.
workload identity 검토	외부 identity, 전용 principal, prod/non-prod 분리, 정확한 claim 검증을 운영할 준비가 있습니다.	매핑 규칙, 짧은 수명 토큰, 필요한 최소 권한, token exchange 오류 관측	토큰 교환을 도입하면 승인·관측·복구가 자동으로 해결된다고 가정하지 않습니다.
전환 보류	production/staging 혼용, 담당자 부재, 로그 노출 위험, 검증 없는 즉시 revoke 중 하나가 있습니다.	보류 사유와 다음 점검 시각	일정 때문에 먼저 폐기하고 나중에 원인을 찾지 않습니다.

Workload identity federation은 신뢰할 수 있는 workload가 이미 가진 identity를 사용하고, 외부 identity provider의 짧은 수명 토큰을 OpenAI의 짧은 수명 access token으로 교환하는 방식입니다. OpenAI의 workload identity federation 문서는 애플리케이션 또는 workload별 전용 principal, production/non-production 분리, broad pattern보다 exact claim matching, 최소 권한, 짧은 access-token lifetime을 권합니다.

따라서 이 방식은 ‘더 현대적인 인증’이라는 이유만으로 선택할 항목이 아닙니다. identity provider와 매핑 규칙을 운영할 사람이 있고, 실패한 token exchange를 관측할 수 있으며, worker별 권한을 좁힐 수 있을 때 검토할 수 있습니다.

정적 API key와 workload identity 중 에이전트 환경에 맞는 인증 방식을 고르는 기준 — 운영 증거가 없으면 기술 선택보다 먼저 전환을 멈추는 결정이 필요합니다.

저위험 worker로 제한 파일럿을 하는 순서

처음에는 고객 데이터 변경이나 결제 같은 부작용이 큰 worker가 아니라, staging과 분리된 저위험 worker 하나를 고르세요. 아래 예시는 실제 key, 조직 ID, secret 경로 없이도 전환 논리를 점검할 수 있는 방식입니다.

대상 고르기: 읽기 전용 또는 되돌릴 수 있는 결과를 내는 worker를 하나 고르고, 담당자와 중단 권한자를 지정합니다.
새 자격증명 배포: 승인된 secret 관리 경로를 통해 새 key를 해당 worker에만 연결합니다. 값 자체를 터미널 출력, 코드, 이미지, 실행 로그에 남기지 않습니다.
최소 요청 실행: 평소 가장 작은 정상 작업을 한 번 실행합니다. 성공 여부, 오류 종류, 실행 시각, 해당 worker의 attribution을 관찰합니다.
관찰 창 유지: 정한 시간 동안 오류가 급증하지 않는지와 예상한 worker만 새 자격증명을 쓰는지를 확인합니다.
cutover 승인: 소유자·성공 증거·복구 방법이 모두 확인됐을 때 기존 key 폐기를 승인합니다.
폐기 후 재확인: 이전 key를 revoke한 뒤에도 최소 요청과 오류 알림을 다시 확인하고, 카드에 결과만 남깁니다.

품질 기준: ‘성공 로그가 한 줄 있다’는 것만으로 충분하지 않습니다. 어떤 worker가, 어떤 환경에서, 누가 승인한 절차로 실행됐는지 연결돼야 다음 교체에도 재사용할 수 있습니다. key 값이나 원문 요청 본문 대신 이 운영 증거를 남기세요.

이 조건에서는 전환을 멈추세요

이전 key를 먼저 revoke하려는 경우: 새 key로 최소 요청을 검증하기 전 폐기는 장애를 확인할 통로까지 닫을 수 있습니다.
staging과 production이 같은 자격증명을 공유하는 경우: 어느 환경의 실패인지 분리할 수 없으면 전환 결과를 믿기 어렵습니다.
key 값이 로그에 남을 가능성이 있는 경우: 로그 마스킹과 secret 전달 경로부터 고쳐야 합니다.
소유자나 복구 담당자가 없는 경우: 교체 작업은 기술 변경이 아니라 운영 책임의 변경이기도 합니다.
workload identity 규칙을 넓게 잡아야만 동작하는 경우: 정확한 claim과 최소 권한으로 설명할 수 있을 때까지 보류하는 편이 낫습니다.

에이전트의 권한과 실행 허가를 더 넓게 점검하려면 에이전트 권한·승인·로그의 운영 경계를, 외부 API 연결 경로를 확인하려면 AI 에이전트 egress 계약 체크리스트를 함께 보세요. GitHub Actions에서 짧은 수명 토큰의 claim을 확인하는 사례는 OIDC 배포 신뢰정책 테스트에서 이어서 확인할 수 있습니다.

자주 묻는 질문

API key 만료일을 짧게 잡으면 자동으로 더 안전해지나요?

그렇지 않습니다. 만료 정책은 노출 기간을 줄이는 데 도움이 될 수 있지만, 새 자격증명 배포와 최소 요청 검증, 복구 책임, 기존 key 폐기 순서가 없으면 작업 중단 위험이 남습니다.

새 key가 한 번 성공하면 바로 이전 key를 폐기해도 되나요?

한 번의 성공만으로 충분하지 않을 수 있습니다. 해당 worker와 환경이 맞는지, 오류 신호는 없는지, 되돌림 담당자가 있는지를 정한 관찰 창 안에서 확인한 뒤 폐기 판단을 하세요.

모든 worker를 workload identity로 바꿔야 하나요?

아닙니다. identity provider, 전용 principal, 정확한 claim 매핑, 환경 분리, 최소 권한, 관측 체계를 운영할 준비가 된 worker부터 검토하면 됩니다. 준비가 안 된 worker는 정적 key를 더 명확한 교체 계약으로 관리하는 편이 나을 수 있습니다.

운영 로그에는 무엇을 남겨야 하나요?

key 값, secret 경로, 요청 원문 대신 worker 이름, 환경, 전환 시각, 최소 요청의 성공·오류 상태, 승인자, 복구 여부처럼 판단에 필요한 운영 증거를 남기세요.

에이전트 실행 환경 안에 장기 자격증명을 넣어도 되나요?

agent-generated code가 환경의 파일과 credentials에 접근할 수 있는 구조라면 특히 주의해야 합니다. 격리, 환경 분리, 승인된 outbound endpoint 제한, 신뢰할 수 있는 경로를 통한 secret 제공을 먼저 검토하세요.

참고 자료

OpenAI Production best practices — API keys: replacement 생성, 애플리케이션 전환, 작동 검증 후 이전 key revoke의 순서를 확인했습니다.
OpenAI Workload identity federation: 외부 identity와 short-lived token 교환, 전용 principal·환경 분리·exact claim·최소 권한 권장 사항을 확인했습니다.
OpenAI Sandbox security: agent 실행 환경의 credentials·network 경계, workload isolation과 승인된 outbound endpoint 제한을 확인했습니다.