How to Use Sentinel (Signup Protection)
Sentinel scores signups for fraud risk. Call its API with an email, domain, or IP and get back an allow, challenge, or block decision before a fake account reaches your product.
Sentinel is ChatFlow's signup-protection service. Your application calls Sentinel's API with an email address (and optionally a domain or IP) when someone signs up, and Sentinel returns a risk decision so you can stop fraudulent and throwaway accounts before they ever reach your product.
Sentinel is a separate product
Sentinel has its own dashboard, its own plans, and a free trial, separate from your ChatFlow chatbot account. You can sign in with the same email, but you onboard into Sentinel on its own. Inside the Sentinel dashboard, the manager roles (Account Manager and above) can view activity; managing API keys, lists, and billing is reserved for Admins and Owners.
How it works
- A visitor signs up on your site.
- Your app calls the Sentinel check endpoint with their email (and optionally domain or IP).
- Sentinel returns a risk level, a score, and a recommendation (allow, challenge, or block).
- Your app acts on the recommendation: let them in, ask for extra verification, or reject the signup.
Step 1: Create your Sentinel account and API key
Open Sentinel and onboard
Go to the Sentinel area and complete onboarding to create your Sentinel workspace. A free trial is available, and you can choose a plan later.
Create an API key
In the Sentinel dashboard, open API Keys and select Create Key. Give it a name (for example, "Production"). The full key is shown once, so copy it and store it somewhere safe. After that you only ever see its prefix.
Test the key
On the same page, use Test API Key: paste the key, enter an email, and run a check to see the risk response right in the dashboard. Test checks also appear in your Activity log.
Step 2: Call the check endpoint
Send a request to the check endpoint with your key in the Authorization header. You can pass an email, a domain, or an ip (at least one is required).
curl "https://chat-flow.app/api/sentinel/v1/[email protected]" \
-H "Authorization: Bearer YOUR_API_KEY"You can also send a POST with a JSON body, which is handy from server code:
curl -X POST "https://chat-flow.app/api/sentinel/v1/check" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "ip": "203.0.113.10" }'The response
{
"risk_level": "high",
"risk_score": 88,
"recommendation": "block",
"categories": ["disposable_email", "no_mx_records"],
"blocked": true,
"is_whitelisted": false,
"is_blacklisted": false,
"has_mx_records": false,
"is_newly_registered": true,
"domain_age_days": 3
}| Field | Meaning |
|---|---|
risk_level | none, low, medium, or high. |
risk_score | A number from 0 (safe) to 100 (high risk). |
recommendation | What to do: allow, allow_with_caution, challenge, or block. |
categories | The reasons behind the score, such as a disposable email address, a flagged connection, or a match on your own lists. |
blocked | true only on the Shield plan when auto-block is on and the risk is high (see below). |
is_whitelisted / is_blacklisted | Whether the value matched one of your custom lists. |
has_mx_records, is_newly_registered, domain_age_days | Extra signals about the email's domain that you can use in your own rules. |
Step 3: Act on the decision
Use recommendation (or your own logic on risk_score) in your signup flow:
| Recommendation | Suggested action |
|---|---|
allow | Let the signup through normally. |
allow_with_caution | Allow, but consider extra monitoring or a lighter verification step. |
challenge | Add friction: email confirmation, a CAPTCHA, or manual review. |
block | Reject the signup. |
Fail open
If a check ever fails or times out, let the signup proceed rather than blocking real customers. Treat Sentinel as a strong signal, not a single point of failure.
Other endpoints
- Batch check at
/api/sentinel/v1/check/batchscores several values in one request. - Status at
/api/sentinel/v1/statusconfirms your key is healthy.
Tune results with custom lists
Open Custom Lists in the dashboard to keep your own blacklist (always block) and whitelist (always allow). Add an email, domain, or IP by hand, or bulk import and export with CSV. Your lists take priority, so a whitelisted address is always allowed and a blacklisted one is always blocked, regardless of the score.
Report threats with community submissions
Under Submissions you can report a bad email, domain, or IP with a reason. Submissions are reviewed, and approved ones help improve protection across Sentinel. Track the status of yours (pending, approved, rejected) on the same page.
Monitor what Sentinel is catching
- The dashboard shows total checks, how many were blocked, challenged, and allowed, recent trends, and your top blocked domains.
- The Activity Log holds the full history of checks. Search by value, filter by risk level or type (email, domain, IP) and date, and export to CSV for your own analysis.
Review the Activity Log regularly and adjust your custom lists as fraud patterns shift.
Plans
Sentinel has two plans, Basic and Shield. Both include unlimited checks, email, domain, and IP scoring, custom lists, and the monitoring dashboard. Shield adds unlimited list entries, community threat intelligence, webhooks, auto-block, advanced analytics, and priority support. Current pricing and a plan comparison are shown in Settings → Subscription in the Sentinel dashboard.
Shield: auto-block
On Shield you can turn on auto-block high-risk signups in Settings. When it is on, the check response sets blocked: true for high-risk results, so your app can reject them on that flag alone.
Shield: webhooks
On Shield, Sentinel can post to a URL you control whenever a risky check comes in, so you can log it, alert your team, or trigger extra verification without polling the API. Configure and test the webhook in Settings.
Verify it's working
- Create an API key and run a check from Test API Key with a known throwaway address. You should see a high risk level.
- Run a check with a normal business email and confirm it comes back low risk.
- Open the Activity Log and confirm both checks appear.
- Add a test address to your whitelist and confirm a check for it now returns allowed.
Troubleshooting
A legitimate signup was flagged
Add the address or its domain to your whitelist, or treat challenge as a verification step rather than an outright block. Use the Activity Log to see which categories triggered the score.
My checks are not appearing in the Activity Log
The log records checks made with a valid, active key. Confirm the key is active in API Keys and that your Authorization header is Bearer YOUR_API_KEY.
I got a 400 error
The request needs at least one of email, domain, or ip. For the POST variant, make sure the body is valid JSON and the Content-Type is application/json.
My plan shows expired
Open Settings → Subscription in the Sentinel dashboard and manage your billing there.