API 레퍼런스

Nginx Proxy Guard API를 사용하여 시스템을 프로그래밍 방식으로 제어합니다.

인증 (Authentication)

모든 API 엔드포인트(/api/v1/auth/login, /api/v1/challenge/* 제외)는 다음 헤더를 통한 인증이 필요합니다.

# JWT Bearer 토큰
Authorization: Bearer <jwt_token>

# API 토큰
Authorization: Bearer ng_<api_token>

인증 (Authentication)

공개 엔드포인트 (인증 불필요)

메서드	엔드포인트	설명
POST	`/api/v1/auth/login`	로그인
POST	`/api/v1/auth/logout`	로그아웃
GET	`/api/v1/auth/status`	인증 상태 확인
POST	`/api/v1/auth/verify-2fa`	2FA 코드 검증

인증 관리

메서드	엔드포인트	설명
GET	`/api/v1/auth/me`	현재 사용자 정보
GET	`/api/v1/auth/account`	계정 상세 정보
POST	`/api/v1/auth/change-credentials`	사용자명/이메일 변경
POST	`/api/v1/auth/change-password`	비밀번호 변경
POST	`/api/v1/auth/2fa/setup`	2FA 설정 시작
POST	`/api/v1/auth/2fa/enable`	2FA 활성화
POST	`/api/v1/auth/2fa/disable`	2FA 비활성화
GET	`/api/v1/auth/language`	언어 설정 조회
PUT	`/api/v1/auth/language`	언어 설정 변경
GET	`/api/v1/auth/font`	폰트 설정 조회
PUT	`/api/v1/auth/font`	폰트 설정 변경

API 토큰 관리

메서드	엔드포인트	설명
GET	`/api/v1/api-tokens`	토큰 목록 조회
POST	`/api/v1/api-tokens`	새 토큰 생성
GET	`/api/v1/api-tokens/permissions`	사용 가능한 권한 목록
GET	`/api/v1/api-tokens/:id`	토큰 상세 정보
PUT	`/api/v1/api-tokens/:id`	토큰 수정
POST	`/api/v1/api-tokens/:id/revoke`	토큰 폐기
DELETE	`/api/v1/api-tokens/:id`	토큰 삭제
GET	`/api/v1/api-tokens/:id/usage`	토큰 사용 통계

프록시 호스트 관리

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts`	목록 조회
POST	`/api/v1/proxy-hosts`	새로운 호스트 생성
GET	`/api/v1/proxy-hosts/by-domain/:domain`	도메인으로 조회
POST	`/api/v1/proxy-hosts/sync`	모든 설정 동기화
GET	`/api/v1/proxy-hosts/:id`	상세 정보 조회
PUT	`/api/v1/proxy-hosts/:id`	호스트 수정
DELETE	`/api/v1/proxy-hosts/:id`	호스트 삭제
POST	`/api/v1/proxy-hosts/:id/test`	연결 테스트

SSL 인증서 관리

메서드	엔드포인트	설명
GET	`/api/v1/certificates`	인증서 목록
POST	`/api/v1/certificates`	Let's Encrypt 인증서 발급
POST	`/api/v1/certificates/upload`	커스텀 인증서 업로드
GET	`/api/v1/certificates/expiring`	만료 예정 인증서 조회
GET	`/api/v1/certificates/:id`	인증서 상세 정보
DELETE	`/api/v1/certificates/:id`	인증서 삭제
POST	`/api/v1/certificates/:id/renew`	인증서 갱신

DNS Provider 관리

메서드	엔드포인트	설명
GET	`/api/v1/dns-providers`	Provider 목록
POST	`/api/v1/dns-providers`	Provider 생성
POST	`/api/v1/dns-providers/test`	자격 증명 테스트
GET	`/api/v1/dns-providers/default`	기본 Provider 조회
GET	`/api/v1/dns-providers/:id`	Provider 상세 정보
PUT	`/api/v1/dns-providers/:id`	Provider 수정
DELETE	`/api/v1/dns-providers/:id`	Provider 삭제

보안 설정 (호스트별)

Rate Limiting

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts/:id/rate-limit`	Rate Limit 조회
PUT	`/api/v1/proxy-hosts/:id/rate-limit`	Rate Limit 설정
DELETE	`/api/v1/proxy-hosts/:id/rate-limit`	Rate Limit 삭제

Fail2ban

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts/:id/fail2ban`	Fail2ban 조회
PUT	`/api/v1/proxy-hosts/:id/fail2ban`	Fail2ban 설정
DELETE	`/api/v1/proxy-hosts/:id/fail2ban`	Fail2ban 삭제

봇 필터

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts/:id/bot-filter`	봇 필터 조회
PUT	`/api/v1/proxy-hosts/:id/bot-filter`	봇 필터 설정
DELETE	`/api/v1/proxy-hosts/:id/bot-filter`	봇 필터 삭제
GET	`/api/v1/bots/known`	알려진 봇 목록

GeoIP 제한

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts/:id/geo`	지역 제한 조회
POST	`/api/v1/proxy-hosts/:id/geo`	지역 제한 생성
PUT	`/api/v1/proxy-hosts/:id/geo`	지역 제한 수정
DELETE	`/api/v1/proxy-hosts/:id/geo`	지역 제한 삭제
GET	`/api/v1/geo/countries`	국가 코드 목록

URI 차단

메서드	엔드포인트	설명
GET	`/api/v1/uri-blocks`	전체 URI 차단 목록
POST	`/api/v1/uri-blocks/bulk-add-rule`	규칙 일괄 추가
GET	`/api/v1/proxy-hosts/:id/uri-block`	호스트별 URI 차단 조회
PUT	`/api/v1/proxy-hosts/:id/uri-block`	호스트별 URI 차단 설정
DELETE	`/api/v1/proxy-hosts/:id/uri-block`	호스트별 URI 차단 삭제
POST	`/api/v1/proxy-hosts/:id/uri-block/rules`	규칙 추가
DELETE	`/api/v1/proxy-hosts/:id/uri-block/rules/:ruleId`	규칙 삭제
GET	`/api/v1/global-uri-block`	전역 URI 차단 조회
PUT	`/api/v1/global-uri-block`	전역 URI 차단 설정
POST	`/api/v1/global-uri-block/rules`	전역 규칙 추가
DELETE	`/api/v1/global-uri-block/rules/:ruleId`	전역 규칙 삭제

보안 헤더

메서드	엔드포인트	설명
GET	`/api/v1/proxy-hosts/:id/security-headers`	보안 헤더 조회
PUT	`/api/v1/proxy-hosts/:id/security-headers`	보안 헤더 설정
DELETE	`/api/v1/proxy-hosts/:id/security-headers`	보안 헤더 삭제
GET	`/api/v1/security-headers/presets`	헤더 프리셋 목록
POST	`/api/v1/proxy-hosts/:id/security-headers/preset/:preset`	프리셋 적용

챌린지 (CAPTCHA)

메서드	엔드포인트	설명
GET	`/api/v1/challenge-config`	전역 챌린지 설정
PUT	`/api/v1/challenge-config`	전역 챌린지 설정 변경
GET	`/api/v1/challenge-config/stats`	챌린지 통계
GET	`/api/v1/proxy-hosts/:id/challenge`	호스트별 챌린지 설정
PUT	`/api/v1/proxy-hosts/:id/challenge`	호스트별 챌린지 설정 변경
DELETE	`/api/v1/proxy-hosts/:id/challenge`	호스트별 챌린지 삭제

클라우드 프로바이더 차단

메서드	엔드포인트	설명
GET	`/api/v1/cloud-providers`	클라우드 프로바이더 목록
GET	`/api/v1/cloud-providers/by-region`	지역별 프로바이더
GET	`/api/v1/cloud-providers/:slug`	프로바이더 상세 정보
GET	`/api/v1/proxy-hosts/:id/blocked-cloud-providers`	차단된 프로바이더 조회
PUT	`/api/v1/proxy-hosts/:id/blocked-cloud-providers`	차단 프로바이더 설정

WAF 관리

WAF 테스트

메서드	엔드포인트	설명
GET	`/api/v1/waf-test/patterns`	테스트 패턴 목록
POST	`/api/v1/waf-test/test`	단일 패턴 테스트
POST	`/api/v1/waf-test/test-all`	전체 패턴 테스트

WAF 규칙 관리

메서드	엔드포인트	설명
GET	`/api/v1/waf/rules`	전체 OWASP CRS 규칙
GET	`/api/v1/waf/hosts`	전체 호스트 WAF 설정
GET	`/api/v1/waf/hosts/:id/config`	호스트별 WAF 설정
GET	`/api/v1/waf/hosts/:id/history`	정책 변경 이력
POST	`/api/v1/waf/hosts/:id/rules/:ruleId/disable`	호스트 규칙 비활성화
POST	`/api/v1/waf/rules/disable-by-host`	도메인별 규칙 비활성화
DELETE	`/api/v1/waf/hosts/:id/rules/:ruleId/disable`	호스트 규칙 활성화
GET	`/api/v1/waf/global/rules`	전역 규칙 상태
GET	`/api/v1/waf/global/exclusions`	전역 예외 목록
GET	`/api/v1/waf/global/history`	전역 정책 이력
POST	`/api/v1/waf/global/rules/:ruleId/disable`	전역 규칙 비활성화
DELETE	`/api/v1/waf/global/rules/:ruleId/disable`	전역 규칙 활성화

IP 차단 관리

메서드	엔드포인트	설명
GET	`/api/v1/banned-ips`	차단된 IP 목록
POST	`/api/v1/banned-ips`	수동 IP 차단
DELETE	`/api/v1/banned-ips/:id`	ID로 IP 차단 해제
DELETE	`/api/v1/banned-ips`	IP 주소로 차단 해제
GET	`/api/v1/banned-ips/history`	차단 이력 조회
GET	`/api/v1/banned-ips/history/stats`	차단 통계
GET	`/api/v1/banned-ips/history/ip/:ip`	특정 IP 이력

리다이렉트 호스트

메서드	엔드포인트	설명
GET	`/api/v1/redirect-hosts`	리다이렉트 목록
POST	`/api/v1/redirect-hosts`	리다이렉트 생성
GET	`/api/v1/redirect-hosts/:id`	리다이렉트 상세
PUT	`/api/v1/redirect-hosts/:id`	리다이렉트 수정
DELETE	`/api/v1/redirect-hosts/:id`	리다이렉트 삭제

접근 목록 (ACL)

메서드	엔드포인트	설명
GET	`/api/v1/access-lists`	접근 목록 조회
POST	`/api/v1/access-lists`	접근 목록 생성
GET	`/api/v1/access-lists/:id`	접근 목록 상세
PUT	`/api/v1/access-lists/:id`	접근 목록 수정
DELETE	`/api/v1/access-lists/:id`	접근 목록 삭제

로그 & 모니터링

대시보드

메서드	엔드포인트	설명
GET	`/api/v1/dashboard`	대시보드 요약 데이터
GET	`/api/v1/dashboard/health`	시스템 건강 상태
GET	`/api/v1/dashboard/health/history`	건강 상태 이력
GET	`/api/v1/dashboard/stats/hourly`	시간별 통계
GET	`/api/v1/dashboard/containers`	Docker 컨테이너 상태
GET	`/api/v1/dashboard/geoip-stats`	GeoIP 통계 데이터

통합 로그

메서드	엔드포인트	설명
GET	`/api/v1/logs`	로그 조회 (필터링)
POST	`/api/v1/logs`	로그 추가
GET	`/api/v1/logs/stats`	로그 통계
GET	`/api/v1/logs/settings`	로그 설정 조회
PUT	`/api/v1/logs/settings`	로그 설정 변경
POST	`/api/v1/logs/cleanup`	오래된 로그 정리
GET	`/api/v1/logs/autocomplete/hosts`	호스트 자동완성
GET	`/api/v1/logs/autocomplete/ips`	IP 자동완성
GET	`/api/v1/logs/autocomplete/user-agents`	User-Agent 자동완성
GET	`/api/v1/logs/autocomplete/countries`	국가 자동완성
GET	`/api/v1/logs/autocomplete/uris`	URI 자동완성
GET	`/api/v1/logs/autocomplete/methods`	HTTP 메서드 자동완성

감사 로그

메서드	엔드포인트	설명
GET	`/api/v1/audit-logs`	감사 로그 조회
GET	`/api/v1/audit-logs/actions`	액션 유형 목록
GET	`/api/v1/audit-logs/resource-types`	리소스 유형 목록
GET	`/api/v1/audit-logs/api-tokens`	API 토큰 사용 이력

시스템 로그

메서드	엔드포인트	설명
GET	`/api/v1/system-logs`	시스템 로그 조회
GET	`/api/v1/system-logs/stats`	시스템 로그 통계
POST	`/api/v1/system-logs/cleanup`	시스템 로그 정리
GET	`/api/v1/system-logs/sources`	로그 소스 목록
GET	`/api/v1/system-logs/levels`	로그 레벨 목록

설정 관리

전역 Nginx 설정

메서드	엔드포인트	설명
GET	`/api/v1/settings`	전역 설정 조회
PUT	`/api/v1/settings`	전역 설정 변경
POST	`/api/v1/settings/reset`	기본값으로 초기화
GET	`/api/v1/settings/presets`	설정 프리셋 목록
POST	`/api/v1/settings/preset/:preset`	프리셋 적용

시스템 설정

메서드	엔드포인트	설명
GET	`/api/v1/system-settings`	시스템 설정 조회
PUT	`/api/v1/system-settings`	시스템 설정 변경
GET	`/api/v1/system-settings/geoip/status`	GeoIP 상태 확인
POST	`/api/v1/system-settings/geoip/update`	GeoIP 데이터베이스 업데이트
GET	`/api/v1/system-settings/geoip/history`	GeoIP 업데이트 이력
POST	`/api/v1/system-settings/acme/test`	ACME 설정 테스트
GET	`/api/v1/system-settings/log-files`	로그 파일 목록
GET	`/api/v1/system-settings/log-files/:filename/download`	로그 파일 다운로드
GET	`/api/v1/system-settings/log-files/:filename/view`	로그 파일 보기
DELETE	`/api/v1/system-settings/log-files/:filename`	로그 파일 삭제
POST	`/api/v1/system-settings/log-files/rotate`	로그 로테이션
GET	`/api/v1/system-settings/logs`	로그 보관 설정
PUT	`/api/v1/system-settings/logs`	로그 보관 설정 변경

백업 & 복원

메서드	엔드포인트	설명
GET	`/api/v1/backups`	백업 목록
POST	`/api/v1/backups`	백업 생성
POST	`/api/v1/backups/upload-restore`	백업 업로드 및 복원
GET	`/api/v1/backups/stats`	백업 통계
GET	`/api/v1/backups/:id`	백업 정보
GET	`/api/v1/backups/:id/download`	백업 다운로드
DELETE	`/api/v1/backups/:id`	백업 삭제
POST	`/api/v1/backups/:id/restore`	백업 복원

테스트 & 검증

메서드	엔드포인트	설명
POST	`/api/v1/test/nginx-config`	Nginx 설정 문법 검사
POST	`/api/v1/test/proxy-host/:id`	프록시 연결 테스트
GET	`/api/v1/test/system/self-check`	시스템 자가 진단
GET	`/api/v1/test/backup-restore`	백업/복원 테스트

시스템 상태

메서드	엔드포인트	설명
GET	`/api/v1/status`	API 상태
GET	`/api/v1/health`	헬스 체크
GET	`/api/docs`	Swagger UI
GET	`/api/docs/swagger.yaml`	Swagger 스펙