KnowBe4 User Management API Guide

Auth method: API Key (Bearer Token)

Setup steps

1. Log in to the KnowBe4 KSAT console as an admin.
2. Navigate to Account Settings > API.
3. Click 'Generate New API Key' and copy the key.
4. Include the key in all requests as an HTTP header: Authorization: Bearer .
5. Note: EU-region accounts use base URL https://eu.api.knowbe4.com/v1; US accounts use https://us.api.knowbe4.com/v1.

List Users

• Method: GET
• URL: https://us.api.knowbe4.com/v1/users
• Watch out for: Returns max 500 users per page. Iterate using the page parameter until an empty array is returned.

Request example

GET /v1/users?page=1&per_page=500
Authorization: Bearer <API_KEY>

Response example

[
  {
    "id": 123456,
    "email": "jdoe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "active",
    "phish_prone_percentage": 12.5
  }
]

Get User by ID

• Method: GET
• URL: https://us.api.knowbe4.com/v1/users/{id}
• Watch out for: The Reporting API is primarily read-only. User creation and updates are not supported via the Reporting API; use SCIM or the KSAT console for writes.

Request example

GET /v1/users/123456
Authorization: Bearer <API_KEY>

Response example

{
  "id": 123456,
  "email": "jdoe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "department": "Engineering",
  "status": "active"
}

List Groups

• Method: GET
• URL: https://us.api.knowbe4.com/v1/groups
• Watch out for: Group membership changes must be made via the KSAT console or SCIM; the Reporting API does not support group membership writes.

Request example

GET /v1/groups?page=1&per_page=500
Authorization: Bearer <API_KEY>

Response example

[
  {
    "id": 789,
    "name": "Engineering",
    "group_type": "console_group",
    "member_count": 42
  }
]

Get Group Members

• Method: GET
• URL: https://us.api.knowbe4.com/v1/groups/{id}/members
• Watch out for: Pagination applies; use page parameter. Returns up to 500 members per page.

Request example

GET /v1/groups/789/members?page=1
Authorization: Bearer <API_KEY>

Response example

[
  {
    "id": 123456,
    "email": "jdoe@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }
]

List Phishing Campaign Results

• Method: GET
• URL: https://us.api.knowbe4.com/v1/phishing/campaigns
• Watch out for: Per-user phishing results are available under /v1/phishing/security_tests/{pst_id}/recipients.

Request example

GET /v1/phishing/campaigns?page=1
Authorization: Bearer <API_KEY>

Response example

[
  {
    "campaign_id": 55,
    "name": "Q1 Phish Test",
    "status": "Closed",
    "phish_prone_percentage": 18.2
  }
]

List Training Enrollments

• Method: GET
• URL: https://us.api.knowbe4.com/v1/training/enrollments
• Watch out for: Large accounts may have tens of thousands of enrollment records; always paginate fully before processing.

Request example

GET /v1/training/enrollments?page=1
Authorization: Bearer <API_KEY>

Response example

[
  {
    "enrollment_id": 9001,
    "user_id": 123456,
    "status": "Passed",
    "completion_percentage": 100
  }
]

Get Account Risk Score

• Method: GET
• URL: https://us.api.knowbe4.com/v1/account/risk_score_history
• Watch out for: Account-level endpoint; not user-specific. Use /v1/users/{id} for per-user risk scores.

Request example

GET /v1/account/risk_score_history
Authorization: Bearer <API_KEY>

Response example

[
  {
    "risk_score": 24.3,
    "date": "2024-01-15"
  }
]

List Users (EU Region)

• Method: GET
• URL: https://eu.api.knowbe4.com/v1/users
• Watch out for: EU-region accounts must use the eu.api.knowbe4.com base URL. Using the US endpoint for EU accounts will return 401 or empty results.

Request example

GET /v1/users?page=1
Authorization: Bearer <API_KEY>

Response example

[
  {
    "id": 654321,
    "email": "eu_user@example.com",
    "status": "active"
  }
]

• Rate limits: KnowBe4 enforces rate limits on the Reporting API. The documented limit is 1,000 requests per minute per API key.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When the rate limit is exceeded, the API returns HTTP 429. Headers X-RateLimit-Limit and X-RateLimit-Remaining are included in responses. Retry logic should use exponential backoff.
• Pagination method: offset
• Default page size: 500
• Max page size: 500
• Pagination pointer: page

• Webhooks available: No
• Webhook notes: KnowBe4 does not offer native outbound webhooks from the KSAT platform as of the current documentation. Event-driven integrations must be achieved by polling the Reporting API.
• Alternative event strategy: Poll the Reporting API on a schedule (e.g., /v1/training/enrollments or /v1/phishing/campaigns) to detect changes. KnowBe4 integrates with SIEM tools via its API for near-real-time data export.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Available across KSAT plans (Silver, Gold, Platinum, Diamond); SSO must be configured as a prerequisite.

• Endpoint: https://training.knowbe4.com/scim/v2

• Supported operations: Create User (POST /Users), Update User (PUT /Users/{id}), Deactivate/Archive User (PATCH /Users/{id} with active=false), List Users (GET /Users), Get User (GET /Users/{id}), Create Group (POST /Groups), Update Group Members (PATCH /Groups/{id}), List Groups (GET /Groups)

Limitations:

• SCIM sync is one-way: IdP pushes to KnowBe4; KnowBe4 does not push changes back to the IdP.
• SSO (SAML) must be configured before SCIM provisioning can be enabled.
• Supported IdPs with documented SCIM integration: Okta and Azure AD (Microsoft Entra ID). Other IdPs may work but are not officially documented.
• Deleting a user via SCIM archives the user in KnowBe4 rather than permanently deleting them.
• Group provisioning via SCIM maps to KnowBe4 console groups; smart groups based on attributes are not created via SCIM.
• SCIM token is generated separately from the Reporting API key within Account Settings > User Management > SCIM.

Three integration patterns cover the majority of production use cases. For new-hire provisioning, configure SAML SSO in the KSAT console first, generate a SCIM token, then connect your IdP (Okta or Azure AD) to the SCIM endpoint - the IdP will POST to /scim/v2/Users for each assigned user.

For bulk user and risk data export, paginate GET /v1/users with page incremented from 1 and per_page=500 until an empty array is returned; extract email, phish_prone_percentage, and status per record.

For offboarding, remove the user from the KnowBe4 app assignment in your IdP; the IdP sends PATCH /scim/v2/Users/{id} with active=false, which archives the user and removes them from active campaigns while preserving historical phishing and training data.

Note that phish_prone_percentage and current_risk_score are computed fields - they cannot be set or overridden via API or SCIM.

Sync new hires from Okta to KnowBe4 via SCIM

1. In KnowBe4 KSAT console, configure SAML SSO with Okta first (prerequisite).
2. Navigate to Account Settings > User Management > SCIM and generate a SCIM token.
3. In Okta Admin, add the KnowBe4 app from the Okta Integration Network and enter the SCIM base URL (https://training.knowbe4.com/scim/v2) and token.
4. Assign users or groups in Okta to the KnowBe4 app; Okta will POST to /scim/v2/Users for each assigned user.
5. Verify users appear in the KnowBe4 KSAT console under Users.

Watch out for: If SSO is not configured before enabling SCIM, provisioning will fail. SCIM is one-way; changes made directly in KnowBe4 console will not sync back to Okta.

Export all users and their phish-prone percentages via Reporting API

1. Generate an API key in KSAT console under Account Settings > API.
2. Send GET https://us.api.knowbe4.com/v1/users?page=1&per_page=500 with Authorization: Bearer .
3. Collect the response array; if it contains 500 records, increment page and repeat.
4. Continue until an empty array is returned.
5. Extract id, email, first_name, last_name, phish_prone_percentage, and status fields from each user object.

Watch out for: Use the correct regional base URL (us vs eu). Large accounts may require dozens of paginated requests; implement retry logic for HTTP 429 responses.

Deactivate a departed employee via SCIM

1. Remove the user from the KnowBe4 app assignment in your IdP (Okta or Azure AD).
2. The IdP will send a PATCH /scim/v2/Users/{id} request with {"active": false} to KnowBe4.
3. KnowBe4 archives the user, revoking console access and removing them from active training campaigns.
4. Historical phishing and training data for the user is retained in KnowBe4 reporting.

Watch out for: Archiving is not the same as deletion; archived users still count toward historical reports. Hard deletion must be performed manually in the KSAT console if required.

The Reporting API enforces a hard pagination ceiling of 500 records per page with no cursor-based pagination; you must increment the page parameter and detect end-of-data by checking for an empty array response.

Rate limiting is set at 1,000 requests per minute per API key; HTTP 429 responses do not include a Retry-After header, so exponential backoff must be implemented manually.

API keys are account-scoped with no granular permission model - any key holder has full read access to all Reporting API data, including phishing results and risk scores, which has access-control implications for multi-team environments. No native webhooks are available; event-driven workflows must be built on polling schedules against /v1/training/enrollments or /v1/phishing/campaigns.

Stitchflow's MCP server with 60+ deep IT/identity integrations handles pagination, retry logic, and regional endpoint routing automatically, removing the most common failure points in custom Reporting API implementations.