攻撃保護の設定を置き換え

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"}}'