공격 방어 설정 전체 교체

PUT /v1/attack-protection · 권한 attack-protection:write

공격 방어 객체 전체를 교체합니다(application/json). 생략한 섹션과 필드는 기본값으로 돌아갑니다. If-Match는 필수입니다. 없으면 428, 오래된 ETag이면 412가 반환됩니다. 같은 객체를 다시 쓰면 아무것도 기록되지 않고 ETag도 유지됩니다. 몇 개의 필드만 바꾸려면 PATCH를 사용하십시오.

요청

필드	타입	필수	설명
`If-Match`	헤더	예	마지막으로 읽은 객체의 `ETag`. 없으면 `428`; 오래되었으면 `412`.
본문	객체	예	설정된 객체, 최대 32 KiB. 각 섹션은 선택 사항이며, 섹션 안의 각 필드도 선택 사항입니다.

필드	타입	범위 또는 값	기본값	하한
`brute_force.mode`	텍스트	`log`, `enforce`	`enforce`
`brute_force.max_failures`	정수	5-100	20	최대 100
`brute_force.window_minutes`	정수	5-60	15
`brute_force.lock_minutes`	정수	5-60	15	최소 5
`brute_force.notify_user`	불리언		`true`
`suspicious_ip_throttling.mode`	텍스트	`log`, `enforce`	`enforce`
`suspicious_ip_throttling.login_failures_per_ip_per_day`	정수	10-10000	100
`suspicious_ip_throttling.signups_per_ip_per_hour`	정수	1-20	20	최대 20
`suspicious_ip_throttling.allowlist`	텍스트 배열	CIDR 접두사 최대 100개; IPv4는 /8보다, IPv6는 /32보다 넓을 수 없음	`[]`
`credential_stuffing.mode`	텍스트	`log`, `enforce`	`enforce`
`credential_stuffing.attack_mode_auto`	불리언		`true`
`credential_stuffing.attack_mode_duration_minutes`	정수	15-240	30
`bot_protection.mode`	텍스트	`off`, `risk_based`, `always`	`risk_based`
`bot_protection.provider`	텍스트	`altcha`	`altcha`
`breached_password.on_signup`	텍스트	`block`	`block`	`block`
`breached_password.on_password_change`	텍스트	`block`	`block`	`block`
`breached_password.on_login`	텍스트	`require_reset`, `notify`	`require_reset`
`breached_password.notify_user`	불리언		`true`
`signup_protection.block_disposable_email`	불리언		`true`
`signup_protection.block_email_subaddress`	불리언		`false`
`signup_protection.max_signups_per_device_30d`	정수	1-50	3
`sms_protection.allowed_countries`	텍스트 배열	ISO 3166-1 alpha-2 코드 최대 250개	`[]` (요금제 기본값)
`sms_protection.daily_cap`	정수 \| null	1-1000000; `null`은 요금제 값	`null`
`sms_protection.conversion_breaker`	불리언		`true`	`true`
`risk_policy.mode`	텍스트	`log`, `enforce` (`enforce`는 Startup 이상 요금제 필요)	`log`
`risk_policy.challenge_threshold`	정수	3-8	4
`risk_policy.block_threshold`	정수 \| null	6-12, `challenge_threshold`보다 커야 함; `null`은 끔	`null`
`risk_policy.notify_user_on_new_device`	불리언		`true`

보안 하한선 아래의 값은 필드의 일반 범위 안에 있더라도 422 below_security_floor로 거부됩니다. 하한선은 모든 환경을 보호하며 낮출 수 없습니다.

동작

변경 사항은 새 로그인에 즉시 적용됩니다. 캐시된 설정은 같은 트랜잭션에서 무효화됩니다.
감사 기록에는 변경된 필드 이름과 이전·새 객체가 포함됩니다.

응답

공격 방어 설정 조회에서와 같은 객체와 새 ETag가 포함된 200 OK입니다.

오류

HTTP	코드	발생 시점
400	`unknown_field`	섹션 또는 필드가 객체에 없습니다. `errors[]`에 포인터가 나열됩니다.
400	`malformed_request`	본문이 올바른 JSON이 아니거나 `If-Match` 헤더가 잘못되었습니다.
401	`unauthenticated`	자격 증명이 없거나, 잘못되었거나, 폐기되었습니다.
403	`insufficient_permissions`	자격 증명에 `attack-protection:write` 권한이 없습니다.
403	`plan_feature_unavailable`	`risk_policy.mode`가 `enforce`인데 요금제에 포함되지 않습니다. 본문에 `feature`와 `required_plan`이 포함됩니다.
412	`precondition_failed`	읽은 후 객체가 변경되었습니다. 다시 읽고 재시도하십시오.
413	`payload_too_large`	객체가 32 KiB보다 큽니다.
422	`validation_failed`	값의 타입이 잘못되었거나 범위를 벗어났거나, `block_threshold`가 `challenge_threshold`보다 크지 않습니다. `errors[]`에 포인터가 나열됩니다.
422	`below_security_floor`	값이 보안 하한선보다 낮습니다. `errors[]`의 각 항목은 `detail`에 필드와 하한선을 적습니다.
422	`allowlist_range_too_broad`	허용 목록 접두사가 IPv4는 /8, IPv6는 /32보다 넓습니다.
428	`precondition_required`	`If-Match`가 없습니다.
429	`rate_limited`	요청 한도를 초과했습니다. `Retry-After` 시간 후에 다시 시도하십시오.
503	`service_unavailable`	종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 시간 후에 다시 시도하십시오.

오류 종류가 여러 개이면 가장 심각한 것만 다음 순서로 반환됩니다: unknown_field, validation_failed, below_security_floor, allowlist_range_too_broad, plan_feature_unavailable. 입력한 값은 응답에 다시 나타나지 않습니다.

예시

curl -X PUT https://api.eu.keenauth.com/v1/attack-protection \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3f1c9a0b5d7e2a4c6b8d0e1f2a3b4c5d"' \
  -d '{"brute_force": {"max_failures": 10, "lock_minutes": 30}, "bot_protection": {"mode": "always"}}'