KnowBe4 API Patterns

KnowBe4 API Patterns

Overview

The KnowBe4 Reporting API provides read access to account data including users, groups, phishing campaigns, training campaigns, and risk scores. Authentication uses Bearer token (API key) in the Authorization header. The API is region-specific -- your base URL depends on where your KnowBe4 account is hosted.

Authentication

Bearer Token Authentication

KnowBe4 uses a simple API key passed as a Bearer token:

GET /v1/users
Authorization: Bearer YOUR_API_KEY
Accept: application/json

Required Headers:

| Header | Value | Description | |--------|-------|-------------| | Authorization | Bearer <API_KEY> | API authentication token | | Accept | application/json | Response format | | Content-Type | application/json | Request body format (for POST/PUT) |

Obtaining an API Key

1. Log into KnowBe4 console as an admin
2. Navigate to Account Settings > API > API Token
3. Click Generate Token (or copy existing)
4. Store securely -- the token has full read access to your account

Environment Variables

export KNOWBE4_API_KEY="your-api-token-here"
export KNOWBE4_REGION="US"  # US, EU, CA, UK, DE

Multi-Region Base URLs

KnowBe4 operates in multiple geographic regions. Your API base URL is determined by your account's region:

| Region | Base URL | Data Center | |--------|----------|-------------| | US | https://us.api.knowbe4.com | United States | | EU | https://eu.api.knowbe4.com | European Union (Frankfurt) | | CA | https://ca.api.knowbe4.com | Canada | | UK | https://uk.api.knowbe4.com | United Kingdom | | DE | https://de.api.knowbe4.com | Germany |

Region Detection

Your region is set when your KnowBe4 account is created and cannot be changed. To determine your region:

1. Log into the KnowBe4 console
2. Check the URL in your browser:
3. training.knowbe4.com = US
4. eu.knowbe4.com = EU
5. ca.knowbe4.com = CA
6. uk.knowbe4.com = UK
7. de.knowbe4.com = DE

Building the Full URL

function getBaseUrl(region) {
  const regionMap = {
    'US': 'https://us.api.knowbe4.com',
    'EU': 'https://eu.api.knowbe4.com',
    'CA': 'https://ca.api.knowbe4.com',
    'UK': 'https://uk.api.knowbe4.com',
    'DE': 'https://de.api.knowbe4.com'
  };

  return regionMap[region.toUpperCase()] || regionMap['US'];
}

// Example: GET https://us.api.knowbe4.com/v1/users
const url = `${getBaseUrl('US')}/v1/users`;

API Versioning

The current API version is v1. All endpoints are prefixed with /v1/:

https://{region}.api.knowbe4.com/v1/{resource}

Common Endpoints

Account

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/account | Account-level information and summary stats |

Users

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/users | List all users | | GET | /v1/users/{user_id} | Get user details | | GET | /v1/users/{user_id}/risk_score_history | User risk score history |

Groups

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/groups | List all groups | | GET | /v1/groups/{group_id} | Get group details | | GET | /v1/groups/{group_id}/members | List group members | | GET | /v1/groups/{group_id}/risk_score_history | Group risk score history |

Phishing

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/phishing/campaigns | List phishing campaigns | | GET | /v1/phishing/campaigns/{campaign_id} | Get campaign details | | GET | /v1/phishing/security_tests | List all security tests | | GET | /v1/phishing/security_tests/{pst_id} | Get security test details | | GET | /v1/phishing/security_tests/{pst_id}/recipients | List test recipients |

Training

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/training/campaigns | List training campaigns | | GET | /v1/training/campaigns/{campaign_id} | Get campaign details | | GET | /v1/training/enrollments | List all enrollments | | GET | /v1/training/enrollments/{enrollment_id} | Get enrollment details |

Store Purchases

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/training/store_purchases | List store purchases | | GET | /v1/training/store_purchases/{purchase_id} | Get purchase details |

Pagination

Request Parameters

KnowBe4 uses page-based pagination with query parameters:

GET /v1/users?page=1&per_page=500

| Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | page | int | 1 | - | Page number (1-based) | | per_page | int | 25 | 500 | Records per page |

Response Headers

Pagination metadata is returned in response headers:

| Header | Description | |--------|-------------| | Total | Total number of records | | Per-Page | Records per page | | Total-Pages | Total number of pages | | Current-Page | Current page number | | Link | Links to first, last, next, prev pages |

Link Header Format

Link: <https://us.api.knowbe4.com/v1/users?page=2&per_page=25>; rel="next",
      <https://us.api.knowbe4.com/v1/users?page=10&per_page=25>; rel="last",
      <https://us.api.knowbe4.com/v1/users?page=1&per_page=25>; rel="first"

Pagination Pattern

async function fetchAllPages(endpoint, apiKey, region) {
  const baseUrl = getBaseUrl(region);
  const allItems = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(`${baseUrl}${endpoint}?page=${page}&per_page=500`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Accept': 'application/json'
      }
    });

    const data = await response.json();
    allItems.push(...data);

    totalPages = parseInt(response.headers.get('Total-Pages') || '1');
    page++;
  } while (page <= totalPages);

  return allItems;
}

Rate Limiting

Limits

| Limit | Value | Scope | |-------|-------|-------| | Requests per day | 1,000 | Per API token | | Requests per minute | Not published | Varies by endpoint |

Rate Limit Response

When rate limited, the API returns HTTP 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded. Please try again later."
}

Retry Strategy

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const jitter = Math.random() * 5000;
      await sleep((retryAfter * 1000) + jitter);
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Rate Limit Best Practices

1. Cache responses -- User lists and group data change infrequently
2. Use per_page=500 -- Minimize number of requests needed
3. Batch reporting queries -- Combine date ranges where possible
4. Monitor daily usage -- Stay well under 1,000 requests/day
5. Spread requests -- Avoid bursts; add small delays between calls

Error Handling

HTTP Status Codes

| Code | Meaning | Action | |------|---------|--------| | 200 | Success | Process response | | 400 | Bad Request | Check query parameters | | 401 | Unauthorized | Invalid or missing API key | | 403 | Forbidden | API key lacks required permissions | | 404 | Not Found | Resource does not exist | | 429 | Rate Limited | Wait and retry with backoff | | 500 | Server Error | Retry with exponential backoff |

Error Response Format

{
  "error": "Description of what went wrong",
  "message": "Additional detail if available"
}

Common Error Scenarios

| Error | Cause | Resolution | |-------|-------|------------| | 401 on all requests | Wrong API key | Regene