Built LMS Help Center

Authentication, Errors, and Limits

Authenticate API requests and handle pagination, rate limits, and error responses.

Use this guide before wiring an integration into production.

Authentication

Every public API request needs an API key.

Authorization: Bearer YOUR_API_KEY

Create and rotate API keys in Admin Dashboard > Settings > Integrations > API Access. Store keys in a secret manager, not in source code, tickets, chat, or screenshots.

API keys are organization-scoped. A key can only access records for the organization that created it, and each endpoint still checks the permissions granted to that key.

Permissions

The public API uses the same permission families as the admin dashboard. Common examples include:

PermissionAllows
users:readRead user records and user search results
users:writeCreate or update users
courses:readRead course records and course search results
courses:writeCreate or update courses
courses:managePublish, unpublish, or perform course admin actions
enrollments:readRead enrollments and progress
enrollments:writeCreate or update enrollments
assessments:readRead exams, attempts, questions, grading, and rubric data
analytics:readRead analytics and reports
admin:apiManage webhooks and API administration endpoints
docs:readFetch the authenticated OpenAPI document

If a request returns 403, compare the endpoint's required permission in the API Reference and Playground with the permissions on the API key.

Pagination

List endpoints use limit and offset.

GET /api/public/v1/users?limit=50&offset=100

Most list endpoints cap limit at 100. Responses usually include pagination fields in meta.

{
  "meta": {
    "total": 250,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Continue requesting pages until has_more is false or the next offset reaches the returned total.

Rate limits

API keys are rate limited. Default API-key traffic is limited to 1,000 requests per hour, and some heavier endpoints may have stricter limits.

When rate limit headers are present, use them to decide when to retry.

HeaderMeaning
X-RateLimit-LimitMaximum requests in the current window
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix timestamp when the limit resets
X-RateLimit-WindowWindow size or start time
Retry-AfterSeconds to wait before retrying a 429 response

Use exponential backoff for retries. Do not retry validation errors or permission errors without changing the request or key permissions.

Error responses

Error responses include a code and message. Some endpoints also include details or a trace ID for support.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "trace_id": "trace_abc123",
    "details": []
  }
}

Common statuses:

StatusCause
400Invalid query parameters or request body
401Missing, malformed, expired, or revoked API key
403API key is valid but lacks the required permission
404Record does not exist or is outside the key's organization
409Request conflicts with an existing record
429Rate limit or quota exceeded
500Server error

Troubleshooting

On this page