API 키 접근 정책

API 키에 호출을 허용할 IP를 지정하는 기능이에요. 정책을 연결한 키는 등록한 IP에서만 API를 호출할 수 있어요.

시크릿 키가 유출되더라도 공격자의 IP는 등록돼 있지 않으므로 호출이 막혀요. 키 유출의 피해를 실제 결제·취소로 번지지 않게 막는 마지막 방어선이에요. 결제 취소, 지급대행 요청처럼 특정 서버에서만 호출하는 API를 사용한다면 등록 효과가 커요.

접근 정책이 영향을 주지 않는 것

접근 정책은 시크릿 키로 서버에서 호출하는 API에만 적용돼요. 아래는 영향을 받지 않으니 등록 대상이 아니에요.

연결할 키 목록에서는 시크릿 키만 골라주세요. 클라이언트 키에는 정책을 적용할 수 없어요.

아래 정보를 입력하세요.

필드	설명
정책 이름	최대 20자. 예: `배치 서버`
정책 설명	최대 100자. 예: `정산 배치 전용`
허용할 IP 주소	서버의 공인 IP. 여러 개는 쉼표(`,`)로 구분하고, CIDR 표기(`198.51.100.0/24`)도 지원해요
연결할 키	정책을 적용할 API 키를 골라주세요

등록을 누르면 정책이 바로 적용되고, 연결한 키는 등록한 IP에서만 호출할 수 있어요. 이미 운영 중인 서버라면 IP를 잘못 등록해서 호출이 막히지 않도록 주의해서 적용하세요.

접근 정책은 테스트・라이브 환경에 각각 등록해야 해요. 화면 상단 탭에서 환경을 전환하세요.

허용할 IP는 서버가 외부에서 사용하는 공인 IP(NAT IP)로 등록해주세요. 잘못된 IP나 내부 가상 IP를 등록하면 정상적인 요청까지 차단될 수 있어요.
라이브 환경에 반영하기 전에 테스트 환경에 먼저 등록해서 API 호출이 정상적으로 이뤄지는지 확인해보세요.
하나의 API 키에는 정책 하나만 연결할 수 있어요. 이미 연결된 정책이 있으면 새 정책으로 교체돼요. 서버가 여러 대라면 정책을 여러 개 만들지 말고 하나의 정책에 IP를 여러 개 넣어주세요.
허용하지 않은 IP에서 호출하면 API_KEY_ACCESS_DENIED(403) 에러가 응답돼요.

서버가 여러 대이고 같은 대역을 쓴다면 CIDR로 묶는 편이 관리하기 편해요. 서버를 증설해도 대역 안이면 정책을 고칠 필요가 없어요.

CIDR 표기 뒤 숫자가 작을수록 넓은 범위를 의미해요. /32는 IP 하나를 뜻하므로 단일 서버를 명시적으로 쓸 때 사용해요.

넓게 잡을수록 편하지만 보호 효과는 약해져요. 필요한 최소 범위로 등록하세요. 실제로 8대를 쓰는데 /16을 등록하면 6만 개 IP를 허용하는 셈이라 접근 정책을 건 의미가 거의 사라져요.

결제 API를 상점 서버가 아니라 호스팅사·연동 솔루션 서버가 호출하는 구조라면, 등록해야 할 IP는 상점 서버가 아니라 그 업체의 서버 IP예요.

상점 서버 IP만 등록하면 정상 결제가 전부 403으로 막혀요. 가장 흔한 실수예요.

업체 IP는 업체 사정으로 바뀔 수 있어요. 변경 시 해당 업체가 사전에 공지하는지 확인하고, 공지를 받는 담당자를 지정해 두세요.

등록해야 하는 것은 서버가 외부로 나갈 때 쓰는 공인 IP(NAT IP) 예요. 서버 내부에서 ifconfig로 보이는 사설 IP(10.x.x.x, 172.16~31.x.x, 192.168.x.x)가 아니에요.

서버에서 아래 명령어를 실행하면 실제 아웃바운드 IP를 확인할 수 있어요.

환경별 주의

AWS: NAT Gateway를 사용하면 NAT Gateway의 EIP, 인스턴스에 EIP가 붙어 있으면 그 EIP예요. 가용영역마다 NAT Gateway가 따로 있으면 전부 등록해야 해요.
오토스케일링: 인스턴스가 늘어도 아웃바운드 IP가 고정되도록 NAT Gateway를 사용하거나 대역 전체를 CIDR로 등록하세요.
쿠버네티스: 노드의 아웃바운드 IP 기준이에요. 노드풀이 여러 개면 전부 확인하세요.
사내망 경유: 회사 방화벽의 공인 IP예요. 인프라 담당자에게 확인하세요.

잘못된 IP나 내부 가상 IP를 등록하면 정상적인 요청까지 차단돼요. 라이브 반영 전에 반드시 테스트 환경에서 확인하세요.