Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ZeraTS/ironbullet/llms.txt

Use this file to discover all available pages before exploring further.

The KeyCheck block is the heart of credential validation in IronBullet. It evaluates conditions against response data to classify each check as Success, Fail, Ban, Retry, or Custom.

​
How KeyCheck Works

KeyCheck contains multiple keychains. Each keychain has:
  • A result (Success/Fail/Ban/Retry/Custom)
  • One or more conditions
  • A mode (AND/OR)
Keychains are evaluated top-to-bottom. The first keychain where all conditions match (AND mode) or any condition matches (OR mode) sets the bot status and stops evaluation.
1

Set Up Your Pipeline

Create a new pipeline with these blocks:
  1. HttpRequest - send login request
  2. ParseJSON - extract data (optional)
  3. KeyCheck - classify the result
This is the standard credential checking pattern.
2

Configure the HTTP Request

Set up your login endpoint:
Method: POST
URL: https://api.example.com/auth/login
Headers:
  Content-Type: application/json
Body:
  {"username":"<input.USER>","password":"<input.PASS>"}
The response is automatically stored in data.SOURCE and data.RESPONSECODE.
3

Create Success Keychain

In the KeyCheck block, add your first keychain:
Result: Success
Mode: AND
Add conditions that indicate a successful login. Common patterns:Pattern 1: Status Code Check
Source: data.RESPONSECODE
Comparison: EqualTo
Value: 200
Pattern 2: Response Contains Token
Source: data.SOURCE
Comparison: Contains
Value: "access_token"
Pattern 3: Specific JSON Field
Source: data.SOURCE
Comparison: Contains
Value: "\"success\":true"
Use AND mode when ALL conditions must be true.
4

Create Fail Keychain

Add a second keychain for failed logins:
Result: Fail
Mode: OR
Common failure indicators:Invalid Credentials
Source: data.SOURCE
Comparison: Contains
Value: "Invalid username or password"
401 Unauthorized
Source: data.RESPONSECODE
Comparison: EqualTo
Value: 401
Wrong Password
Source: data.SOURCE
Comparison: Contains
Value: "incorrect password"
Use OR mode so any failure message triggers a Fail.
5

Handle Bans and Rate Limits

Add keychains for ban detection (should be BEFORE Fail):
Result: Ban
Mode: OR
Conditions:
Source: data.RESPONSECODE
Comparison: EqualTo
Value: 429

Source: data.SOURCE
Comparison: Contains
Value: "Too many requests"

Source: data.SOURCE
Comparison: Contains
Value: "rate limit"
When a check is marked as Ban:
  • The proxy (if used) is temporarily banned
  • The data line is re-queued with a different proxy
  • Helps avoid burning through your entire proxy pool
6

Add Retry for Timeouts

Add a Retry keychain for temporary errors:
Result: Retry
Mode: OR
Conditions:
Source: data.RESPONSECODE
Comparison: EqualTo
Value: 0
(Response code 0 means connection timeout)
Source: data.RESPONSECODE
Comparison: EqualTo
Value: 502
(Bad Gateway - server temporarily down)Retry entries are re-queued up to max_retries times (set in Runner settings).
7

Test Your KeyCheck Logic

Press F5 to debug with test credentials.Try different scenarios:
  • Valid login
  • Invalid password
  • Rate limit response (if you can trigger it)
  • Timeout (by using an unreachable URL)
Check the Result in the debug panel matches your expectations.

​
Real-World Example: Multi-Step Login

Some sites return different responses for “user doesn’t exist” vs “wrong password”. Here’s how to capture both: 
Pipeline:
  1. HttpRequest (POST /login)
  2. KeyCheck

KeyCheck Keychains:
  1. Success (AND)
     - data.SOURCE Contains "dashboard"
     - data.RESPONSECODE EqualTo 200

  2. Custom "2FA Required" (AND)
     - data.SOURCE Contains "verification_code"
     - data.RESPONSECODE EqualTo 200

  3. Fail "Invalid User" (OR)
     - data.SOURCE Contains "user not found"
     - data.SOURCE Contains "email does not exist"

  4. Fail "Wrong Password" (OR)
     - data.SOURCE Contains "incorrect password"
     - data.SOURCE Contains "invalid credentials"

  5. Ban (OR)
     - data.RESPONSECODE EqualTo 429
     - data.SOURCE Contains "captcha"

  6. Retry (OR)
     - data.RESPONSECODE EqualTo 0
     - data.RESPONSECODE EqualTo 502

​
Advanced: Using Parsed Variables

Combine ParseJSON with KeyCheck for precise checks: 
1. HttpRequest (POST /api/auth)
2. ParseJSON
   - JSON Path: status
   - Output Variable: AUTH_STATUS
   - Capture: false

3. ParseJSON
   - JSON Path: user.role
   - Output Variable: USER_ROLE
   - Capture: true

4. KeyCheck
   - Keychain 1 (Success AND):
       * AUTH_STATUS EqualTo "authenticated"
       * USER_ROLE NotEqualTo "banned"
Now your Success hits will include the user’s role: 
admin@example.com:password123 | USER_ROLE=administrator

​
Comparison Operators

OperatorUse Case
ContainsCheck if response contains a substring
NotContainsResponse must NOT contain substring
EqualToExact match (case-sensitive)
NotEqualToMust not match
MatchesRegexAdvanced pattern matching
GreaterThanNumeric comparison
LessThanNumeric comparison
ExistsVariable is defined
NotExistsVariable is undefined

​
Tips

Order matters! Place more specific keychains (Success, Custom, Ban) BEFORE generic ones (Fail, Retry).
If NO keychain matches, the status remains None and the entry is marked as an error. Always add a catch-all Fail keychain at the end.
Use data.ADDRESS to check the final URL after redirects. Useful for detecting login redirects vs error pages.

​
Debugging KeyCheck Issues

  1. All entries show as Error
    • No keychain matched → add a catch-all Fail keychain
    • Check your condition values for typos
  2. Success/Fail reversed
    • Check keychain order (Success before Fail)
    • Verify your condition logic (AND vs OR)
  3. Random failures on valid combos
    • Add Ban detection for rate limits
    • Lower thread count to reduce request rate
    • Enable proxy rotation

​
Next Steps

Working with Proxies

Add proxy rotation to avoid bans

Browser Automation

Handle Cloudflare and JavaScript-rendered responses

Build docs developers (and LLMs) love

Get started for freeTalk to us