# Knowbe4

SureCloud connects to KnowBe4 to retrieve security awareness training completion status, phishing simulation campaign results, and user risk scores. This allows SureCloud to verify that employees have completed required security training within defined timeframes, that phishing simulation programmes are running, and that training compliance rates are being tracked — providing continuous evidence for security awareness controls.

## Authentication and setup

KnowBe4 authenticates API requests using an API token. SureCloud uses a token generated within your KnowBe4 account.

{% stepper %}
{% step %}
**Generate an API token in KnowBe4**

Log in to your KnowBe4 account. Navigate to **Account Settings → API** and click **Generate Token**. Give it a name such as `SureCloud CCM`. Copy the token — it may only be displayed once.
{% endstep %}

{% step %}
**Enter the token in SureCloud**

Navigate to **SureCloud → Integrations → KnowBe4 → Connect**. Paste the API token and click **Save**.
{% endstep %}

{% step %}
**Test the connection**

Click **Test Connection**. SureCloud will call `GET /v1/users` to verify the token and confirm data access.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **KnowBe4 → Account Settings → API** and update it in **SureCloud → Integrations → KnowBe4 → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                      | Use Case                                                                      |
| --------------------------------------------- | ----------------------------------------------------------------------------- |
| `GET /v1/users`                               | Enumerate all users including their current risk score and status             |
| `GET /v1/users/{id}/enrollment`               | Retrieve training enrolment and completion status per user                    |
| `GET /v1/training/campaigns`                  | List training campaigns to confirm required training is assigned              |
| `GET /v1/training/campaigns/{id}/enrollments` | Retrieve enrolment and completion records for a specific campaign             |
| `GET /v1/phishing/campaigns`                  | List phishing simulation campaigns and their current status                   |
| `GET /v1/phishing/campaigns/{id}/results`     | Retrieve phishing simulation results including click rate and failure details |
| `GET /v1/groups`                              | Enumerate user groups for training scope mapping                              |

## Pagination

`GET /v1/users` and `GET /v1/training/campaigns/{id}/enrollments` return up to 500 results per page. SureCloud uses the `page` parameter to retrieve subsequent pages until the returned count is less than the page size.

```json
GET /v1/users?page=2&per_page=500
```

`GET /v1/phishing/campaigns/{id}/results` uses the same pattern.

## Required permissions

KnowBe4 API tokens are account-scoped. The token requires read access to:

* Users and groups (read)
* Training campaigns and enrolments (read)
* Phishing campaigns and results (read)

Standard KnowBe4 API tokens provide this access for administrator accounts. No write, assign, or launch permissions are required.

## Polling frequency

| Data Type                            | Interval       |
| ------------------------------------ | -------------- |
| User training completion status      | Every 24 hours |
| Training campaign enrolment records  | Every 24 hours |
| Phishing simulation campaign results | Every 24 hours |
| User risk scores                     | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API token is invalid or has been revoked. Navigate to **KnowBe4 → Account Settings → API**, confirm the token is active, and regenerate it if necessary. Update it in **SureCloud → Integrations → KnowBe4 → Edit Connection**.

</details>

<details>

<summary>Training completion data is incomplete for some users</summary>

Training enrolments are associated with campaigns. If a user was enrolled in a campaign that has since been archived or deleted in KnowBe4, their enrolment records may not be returned by the active campaigns endpoint. SureCloud collects enrolments from active campaigns. For historical evidence of archived campaigns, export records directly from the KnowBe4 console.

</details>

<details>

<summary>Phishing campaign results show low click counts</summary>

KnowBe4 phishing results reflect user interactions at the time SureCloud polls the API. Results accumulate throughout the campaign duration. If SureCloud collects early in a campaign, click rates will reflect partial results. Wait until the campaign has concluded and run a manual refresh from **SureCloud → Integrations → KnowBe4** for final campaign evidence.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/knowbe4.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.