API access

The Kokobi HTTP API lets your systems manage learning resources and read progress without reproducing administrator actions in the browser. The interactive OpenAPI reference is available at /api/docs.

Create an API Key#

Organization owners and administrators can manage organization API keys from the organization switcher in the Admin sidebar:

1. Open Admin and select the organization switcher.
2. Choose API keys.
3. Enter a descriptive name for the integration.
4. Create the key.
5. Copy the secret immediately and store it in a secret manager.

The full key is only displayed when it is created. Use separate keys for separate applications so one integration can be revoked without interrupting another.

API keys are scoped to an organization and are subject to the same rate limits as the associated account. The key's organization becomes the active organization for authenticated API operations.

Authenticate Requests#

Send the key in the x-api-key request header:

curl "https://your-kokobi-host.example/api/courses" \  --header "x-api-key: $KOKOBI_API_KEY" \  --header "accept: application/json"

Do not put API keys in URLs, browser code, logs, analytics properties, or committed configuration files.

Find an Endpoint#

Open /api/docs for the current endpoint catalog, request schemas, response schemas, and error responses. Major groups include:

• Courses, modules, learners, sharing, and statistics.
• Collections, ordered courses, and collection learners.
• Learner-facing courses, attempts, and collections.
• Organizations, domains, and organization learners.
• Webhook configuration and delivery history.
• Public course, collection, and organization reads.

Use the operation and schema shown in the interactive reference as the source of truth. The API is served under /api on both the main Kokobi host and an active organization custom domain.

Localization#

Localized endpoints select English or French using the first available value from:

1. A locale query parameter.
2. A locale request header.
3. The locale cookie.
4. The Accept-Language header.
5. English as the default.

Some resource endpoints also expose a fallback locale option. Consult the endpoint schema in /api/docs before disabling fallback behavior.

Example:

curl "https://your-kokobi-host.example/api/courses?locale=fr" \  --header "x-api-key: $KOKOBI_API_KEY" \  --header "accept: application/json"

Errors#

Handle status codes explicitly. Responses vary by operation; use the error schemas in the interactive reference as the source of truth.

Validate outgoing payloads, use bounded retries only for transient failures, and never retry validation or permission errors without changing the request.

Security Practices#

• Store the key in a server-side secret manager.
• Grant and use the least access needed for the integration.
• Rotate keys periodically and immediately after suspected exposure.
• Delete keys that are no longer used.
• Keep development and production keys separate.
• Avoid exposing learner data to systems that do not need it.
• Log request IDs and status codes rather than secrets or full personal-data payloads.

For event-driven integrations, prefer webhooks over repeatedly polling the API.

Related Guides#

• Webhooks
• Organizations
• Custom domains