KnowBe4 Security Awareness Training + PhishER

At a glance

Vendor	KnowBe4 — Security Awareness Training platform + PhishER incident-response add-on.
Source type	training
Vendor ID (slug)	knowbe4
Base URL	Regional. https://us.api.knowbe4.com (default, US), eu.api, ca.api, uk.api, de.api.
Auth method	api-key — KnowBe4 Reporting API token (Bearer header). Dispatcher emits it automatically; no override needed.
Schedule default	daily — training and phishing-test data update slowly; hourly adds cost without new signal. Override to hourly only for the PhishER-unresolved KRI if you need tighter response.
Licensing	Core KRIs need the base KnowBe4 Reporting API. The PhishER unresolved-high KRI requires a separate PhishER subscription with its own API token — pass via Extra Config. Tenants without PhishER get 0 + warn log on that one KRI.
Availability	New in 2026.04.

Required scopes & roles

KnowBe4 has a single admin API token per account — no role-based scoping. The token inherits the admin's full read capabilities. Treat it as sensitive; KnowBe4 does NOT support IP allowlists on API tokens at the time of writing.

• Reporting API Access — Account Settings → API. Enable the toggle; copy the generated token.
• User-level API Access — Required for per-user PPP / risk-score reads (most of the KRIs). Toggle within the same settings panel.
• PhishER API Access — Separate toggle; required only for the PhishER KRI. Generates a separate token — put it in Draxis's Extra Config as phisher_token.

Do not share the token across multiple integrations. If it leaks, your only remediation is to rotate the single admin API token — which breaks every other integration using it at the same time.

Setup steps

1. Identify your KnowBe4 region. Sign into your KnowBe4 console and look at the URL — e.g. training.knowbe4.com (US), training.eu.knowbe4.com (EU). The API hostname follows the pattern https://<region>.api.knowbe4.com.
2. Enable the Reporting API. In the KnowBe4 console: Account Settings → API → Reporting API Access → Enable. Copy the generated token — KnowBe4 shows it once.
3. Enable User-level API Access. Same settings panel; toggle User-level API Access. This uses the same token.
4. (Optional) Enable PhishER API. If you license PhishER, go to the PhishER console → Settings → API → generate a PhishER API token. Note the PhishER base URL (often same as KnowBe4's region, but in some tenants it's a separate endpoint — check the PhishER console for the API base URL).
5. Verify connectivity with a quick curl before wiring Draxis:

   curl -s -H 'Authorization: Bearer <token>' \
     'https://us.api.knowbe4.com/v1/account' \
     | jq '.name, .subscription_level, .number_of_seats'

   Should print your org name, subscription tier, and seat count. 401 means token is wrong; 403 means the API access toggle isn't enabled.

Wire it into Draxis

1. Open Settings → Integrations in your tenant.
2. Click Add integration and pick Security Awareness Training as the source type.
3. Pick KnowBe4 Security Awareness Training + PhishER from the vendor dropdown. Draxis pre-fills the US regional base URL, Bearer auth, daily schedule, and seeds extra_config_json with {"phisher_token":"","phisher_base":""}.
4. If you're outside US, override API Base URL to your region (e.g. https://eu.api.knowbe4.com).
5. In API Key / Token, paste the KnowBe4 Reporting API token. Draxis encrypts it server-side with encryption.key before storage.
6. In Extra Config, paste your PhishER API token into phisher_token if you have PhishER. Leave phisher_base empty to use the same base URL as KnowBe4; set it if PhishER is on a different host in your tenant.
7. Click Test. Green means Draxis called /v1/account successfully — the message includes your org name, subscription level, and seat count.
8. Under KRIs to import, tick the KRIs you want Draxis to manage. All ten kb4_* KRIs are checked by default; uncheck the PhishER KRI if you don't have PhishER, and uncheck the remedial-compliance KRI if your org doesn't use "remedial" in campaign names (see Quirks). Selected rows are created on save.
9. Save. The connector runs daily by default.

KRIs produced

Slug	Meaning	Derivation
kb4_phishing_prone_pct	Org-wide average Phishing Prone Percentage	GET /v1/users?status=active paginated; average phish_prone_percentage across all active users.
kb4_repeat_clickers_90d	Users who clicked in 2+ phishing simulations in 90d	GET /v1/phishing/security_tests?since=<now-90d> → for each test, GET /v1/phishing/security_tests/{id}/recipients. Count clicks per user; filter to users with ≥2.
kb4_training_completion_pct	% of past-due enrollments completed on time	GET /v1/training/enrollments → filter to due_date < now; of those, count where status=Completed AND completion_date ≤ due_date divided by the total past-due count.
kb4_overdue_training_assignments	Past-due enrollments NOT completed	Same enrollment dump as #3; count where due_date < now AND status != Completed/Passed.
kb4_remedial_training_compliance_pct	% of remedial-training enrollments completed	Filter enrollment dump to campaigns with "remedial" in name (case-insensitive); count completed / total in that subset.
kb4_high_risk_users	Users in top decile by risk score	Sort users by current_risk_score desc; count = ceil(total × 0.10).
kb4_phish_time_to_report_hours	Median hours from phish delivery to user report	From the security-test recipient dump: for each recipient where both delivered_at and reported_at are set, compute the delta. Median across all such deltas.
kb4_phisher_unresolved_high_4h	PhishER high-severity reports unresolved >4h	GET <phisher_base>/phisher/v1/messages?severity=high&status=unresolved&reported_at_min=<now-24h>&reported_at_max=<now-4h> using the PhishER token. Skipped with 0 if phisher_token is not set.
kb4_zero_training_activity_12m	Active users with no activity in 12 months	From the users dump: count where last_activity_at is null OR older than now - 365d.
kb4_department_ppp_delta_pct	Max − min group-level average PPP	From the users dump: group each user's PPP by their groups[]; average PPP per group; return the spread between the highest and lowest group average.

Each row is a slug the connector writes to. Draxis creates the matching kri rows automatically when you check them in the KRIs to import section of the integration form — no manual API call or seed script needed. Thresholds shown in the table are the seeded defaults; you can edit them freely in the KRIs tab afterwards.

Vendor quirks

• Single admin token, no role scoping. KnowBe4's Reporting API has one token per account that grants admin-level read across every KnowBe4 product the account owns. There's no way to scope a token to specific endpoints or restrict by IP. Treat it like a password — rotate on any hint of exposure, even though rotation breaks all other integrations at the same time.
• PhishER uses a separate token. PhishER data isn't accessible via the Reporting API token. Pass the PhishER token in Extra Config (phisher_token). If your PhishER API is on a different base URL than the main KnowBe4 API, also set phisher_base.
• Training completion rate denominator is past-due enrollments only. Including pending-but-not-due enrollments deflates the percentage (they're neither complete nor overdue yet). The KRI scopes the denominator to due_date < now so the value reflects on-time completion performance, not overall campaign progress.
• Remedial-compliance KRI depends on campaign naming. The KRI filters training campaigns whose name contains "remedial" (case-insensitive). KnowBe4 doesn't expose a direct "remedial vs standard" flag in the API — if your org uses different language (e.g. "Phish Follow-Up"), the KRI will read 0 even when you run remedial programs. Rename the campaigns or tune the filter in the connector.
• High-risk user decile is count, not threshold. The KRI returns the headcount of the top 10% — so a 1000-user org always shows 100, and the signal comes from trending over time or comparing to thresholds you set. Pair with the PPP KRI to see whether the risk distribution is shifting.
• Time-to-report needs both delivery and report timestamps. KnowBe4's phishing-test recipients data includes delivered_at and reported_at. Some tests (legacy or custom) may not record delivery timestamps — those recipients are excluded from the median calculation. If the KRI reads 0 and you know you have reports, the security tests might be misconfigured for delivery tracking.
• Department delta assumes users have groups assigned. KnowBe4 groups map loosely to departments. Users with no groups don't contribute to the delta (their PPP doesn't land in any bucket). If your org doesn't use groups aggressively, this KRI reads 0.
• Page caps on large orgs. Users cap at 25k (50 pages × 500). Enrollments cap at 25k. Phishing tests cap at ~5k per 90d window. Orgs exceeding these will see a truncated warn in the run log — KRI values are still directionally useful but may be lower bounds.
• PhishER pagination semantics are different. PhishER's API envelope returns items directly rather than via a total_count field. The connector paginates and counts client-side, capped at 20 pages × 500 messages.
• Ten KRIs is a lot. User-requested. Consider which subset matches your actual security-awareness program focus — the default-checked selection in the import form is aggressive. A lean program might check just PPP, repeat clickers, training completion, and high-risk users.
• Rate limits. KnowBe4 documents 1000 req/hour per token. A single daily run makes roughly 150-300 calls on a 5k-user org, so rate-limiting is not a concern at daily scheduling. Hourly scheduling on large orgs might push closer to the limit.

Troubleshooting

• HTTP 401 on Test — token is wrong or Reporting API Access toggle isn't enabled. Regenerate in Account Settings → API.
• HTTP 403 on specific endpoints — User-level API Access toggle isn't enabled (blocks /v1/users + related). Enable it in the same settings panel.
• HTTP 404 on every endpoint — wrong regional base URL. Match the region where your KnowBe4 account is hosted (US / EU / CA / UK / DE).
• kb4_phisher_unresolved_high_4h is 0 with "phisher_token not set" — expected if you don't have PhishER. Uncheck that KRI if the 0 reads as misleading.
• kb4_remedial_training_compliance_pct is 100 on an org you know has remedial programs — your campaign names don't contain "remedial". Either rename the campaigns or edit the filter in the connector file.
• kb4_department_ppp_delta_pct is 0 — either users aren't assigned to groups, or all groups have identical PPP. Check in the KnowBe4 console that users have group memberships.
• Repeat clickers / time-to-report KRIs read as 0 after migration to new phishing tests — new tests don't yet have 90 days of history. Wait 30+ days before interpreting these KRIs as "low risk".
• rowsSkipped > 0 and rowsWritten = 0 — your tenant hasn't imported any KRIs for this integration yet. Open the integration in Settings → Integrations, tick the KRIs under KRIs to import, and save.
• Still stuck? Open a support ticket with the run ID (from Run history) and we'll dig in.