API 키 접근 정책
API 키에 호출을 허용할 범위를 지정하는 기능이에요. 허용 범위로 IP 주소나 국가를 선택할 수 있어요. 정책을 연결한 키는 등록한 범위 안에서만 API를 호출할 수 있어요.
시크릿 키가 유출되더라도 공격자의 IP는 등록돼 있지 않으므로 호출이 막혀요. 키 유출의 피해가 실제 결제·취소로 번지지 않게 막는 마지막 방어선이에요. 결제 취소, 지급대행 요청처럼 특정 서버에서만 호출하는 API를 사용한다면 등록 효과가 커요.
접근 정책이 영향을 주지 않는 것
접근 정책은 시크릿 키로 서버에서 호출하는 API에만 적용돼요. 아래는 영향을 받지 않으니 등록 대상이 아니에요.
- 구매자 브라우저에서 클라이언트 키로 여는 결제 UI·결제창(SDK). 구매자 IP는 제한할 수 없고, 제한해서도 안 돼요.
- 토스페이먼츠가 상점 서버로 보내는 웹훅. 방향이 반대라 접근 정책과 무관해요. 웹훅 수신 방화벽은 인바운드 IP 목록으로 따로 열어주세요.
연결할 키 목록에서는 시크릿 키만 골라주세요. 클라이언트 키에는 정책을 적용할 수 없어요.
정책 등록하기
-
개발자센터의 API 키 접근 정책 메뉴를 열고 등록하기를 누르세요.
-
아래 정보를 입력하세요.
필드 설명 정책 이름 최대 20자. 예: 배치 서버정책 설명 최대 100자. 예: 정산 배치 전용허용 범위 IP 주소또는국가중 하나를 선택해주세요허용할 값 • IP 주소: 서버의 공인 IP. 여러 개는 쉼표( ,)로 구분하고, CIDR 표기(198.51.100.0/24)도 지원해요
• 국가: 검색으로 최대 10개국까지 추가할 수 있어요연결할 키 정책을 적용할 API 키를 골라주세요 -
등록을 누르면 정책이 바로 적용되고, 연결한 키는 등록한 IP에서만 호출할 수 있어요. 이미 운영 중인 서버라면 IP를 잘못 등록해서 호출이 막히지 않도록 주의해서 적용하세요.
접근 정책은 테스트・라이브 환경에 각각 등록해야 해요. 화면 상단 탭에서 환경을 전환하세요.
- 허용할 IP는 서버가 외부에서 사용하는 공인 IP(NAT IP)로 등록해주세요. 잘못된 IP나 내부 가상 IP를 등록하면 정상적인 요청까지 차단될 수 있어요.
- 라이브 환경에 반영하기 전에 테스트 환경에 먼저 등록해서 API 호출이 정상적으로 이뤄지는지 확인해보세요.
- 하나의 API 키에는 정책 하나만 연결할 수 있어요. 이미 연결된 정책이 있으면 새 정책으로 교체돼요. IP 주소와 국가를 동시에 등록할 수 없어요. 서버가 여러 대라면 정책을 여러 개 만들지 말고 하나의 정책에 IP를 여러 개 넣어주세요.
- 서버의 공인 IP를 알고 있으면
IP 주소를, 서버 IP가 자주 바뀌거나 미리 알기 어려우면국가를 선택하세요. - 허용 범위 밖에서 호출하면
API_KEY_ACCESS_DENIED(403) 에러가 응답돼요.
IP 주소 등록 예시
서버 여러 대 (쉼표 구분)
CIDR 표기로 대역 등록
서버가 여러 대이고 같은 대역을 쓴다면 CIDR로 묶는 편이 관리하기 편해요. 서버를 증설해도 대역 안이면 정책을 고칠 필요가 없어요.
CIDR 표기 뒤 숫자가 작을수록 넓은 범위를 의미해요. /32는 IP 하나를 뜻하므로 단일 서버를 명시적으로 쓸 때 사용해요.
| 표기 | 포함되는 IP | 개수 |
|---|---|---|
203.0.113.10/32 | 203.0.113.10 | 1 |
203.0.113.0/29 | 203.0.113.0 ~ 203.0.113.7 | 8 |
203.0.113.0/28 | 203.0.113.0 ~ 203.0.113.15 | 16 |
203.0.113.0/24 | 203.0.113.0 ~ 203.0.113.255 | 256 |
198.51.0.0/16 | 198.51.0.0 ~ 198.51.255.255 | 65,536 |
넓게 잡을수록 편하지만 보호 효과는 약해져요. 필요한 최소 범위로 등록하세요. 실제로 8대를 쓰는데 /16을 등록하면 6만 개 IP를 허용하는 셈이라 접근 정책을 건 의미가 거의 사라져요.
대역과 단일 IP 혼합
국가 단위로 허용하기
서버의 공인 IP를 미리 알기 어렵거나 자주 바뀌는 환경이라면, IP 주소 대신 국가로 허용 범위를 지정할 수 있어요. 정책 하나당 최대 10개국까지 검색으로 추가할 수 있어요.
동작 원리
국가 단위 정책은 API를 호출하는 상점 서버의 공인 IP가 지리적으로 어느 국가에 있는지를 기준으로 판단해요. 구매자의 IP가 아니라 API를 호출한 서버의 IP 기준이에요.
예를 들어 허용 국가로 대한민국만 등록해두면, 국내 서버에서 호출한 요청은 정상 처리되고, 시크릿 키가 유출되어 해외 서버에서 호출되는 요청은 차단돼요.
영향 범위
| 호출 유형 | 국가 정책 적용 여부 |
|---|---|
| 시크릿 키로 서버에서 호출하는 API | ✅ 상점 서버의 IP가 등록 국가 안에 있어야 호출돼요 |
| 구매자가 결제창에서 여는 결제 UI(SDK) | ❌ 영향 없어요. 구매자 IP는 제한하지 않아요 |
| 토스페이먼츠가 상점 서버로 보내는 웹훅 | ❌ 영향 없어요 |
해외 리전 서버는 그 리전의 국가를 추가로 등록해주세요 — 국가 판단은 상점 사업자의 국적이 아니라 API를 호출한 서버의 공인 IP 위치로 이뤄져요. 예를 들어 한국 사업자가 AWS 도쿄 리전 서버에서 API를 호출하면 호출 IP는 일본으로 식별돼요. 이때 허용 국가에 대한민국만 등록되어 있으면 모든 요청이 API_KEY_ACCESS_DENIED(403)로 차단돼요.
- AWS 도쿄 리전에서 호출 →
일본추가 - AWS 싱가포르 리전에서 호출 →
싱가포르추가 - 한국·해외 리전 동시 운영 → 두 국가 모두 등록
결제창(클라이언트 키)은 영향받지 않아요 — 국가 단위 정책은 시크릿 키로 서버에서 호출하는 API에만 적용돼요. 구매자가 해외에서 결제창을 여는 상황은 차단되지 않으니, 해외 구매자 결제 때문에 국가 정책 적용을 망설일 필요는 없어요.
연동 솔루션을 이용할 때
결제 API를 상점 서버가 아니라 호스팅사·연동 솔루션 서버가 호출하는 구조라면, 등록해야 할 IP는 상점 서버가 아니라 그 업체의 서버 IP예요.
상점 서버 IP만 등록하면 정상 결제가 전부 403으로 막혀요. 가장 흔한 실수예요.
| 이용 형태 | 등록해야 할 IP |
|---|---|
| 자체 서버에서 직접 호출 | 상점 서버의 아웃바운드 공인 IP |
| 호스팅사 솔루션이 호출 | 호스팅사가 안내하는 결제 서버 IP 대역 |
| 자체 서버 + 솔루션 혼용 | 양쪽 모두 |
| 외주사가 운영 대행 | 외주 운영 서버 IP까지 포함 |
업체 IP는 사정에 따라 바뀔 수 있어요. 변경 시 해당 업체가 사전에 공지하는지 확인하고, 공지를 받는 담당자를 지정해 두세요.
공인 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를 등록하면 정상적인 요청까지 차단돼요. 라이브 반영 전에 반드시 테스트 환경에서 확인하세요.