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:

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 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:
   • training.knowbe4.com = US
   • eu.knowbe4.com = EU
   • ca.knowbe4.com = CA
   • uk.knowbe4.com = UK
   • 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

Users

Groups

Phishing

Training

Store Purchases

Pagination

Request Parameters

KnowBe4 uses page-based pagination with query parameters:

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

Response Headers

Pagination metadata is returned in response headers:

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

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

Error Response Format

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

Common Error Scenarios