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_KEYCreate 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:
| Permission | Allows |
|---|---|
users:read | Read user records and user search results |
users:write | Create or update users |
courses:read | Read course records and course search results |
courses:write | Create or update courses |
courses:manage | Publish, unpublish, or perform course admin actions |
enrollments:read | Read enrollments and progress |
enrollments:write | Create or update enrollments |
assessments:read | Read exams, attempts, questions, grading, and rubric data |
analytics:read | Read analytics and reports |
admin:api | Manage webhooks and API administration endpoints |
docs:read | Fetch 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=100Most 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.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Maximum requests in the current window |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix timestamp when the limit resets |
X-RateLimit-Window | Window size or start time |
Retry-After | Seconds 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:
| Status | Cause |
|---|---|
| 400 | Invalid query parameters or request body |
| 401 | Missing, malformed, expired, or revoked API key |
| 403 | API key is valid but lacks the required permission |
| 404 | Record does not exist or is outside the key's organization |
| 409 | Request conflicts with an existing record |
| 429 | Rate limit or quota exceeded |
| 500 | Server error |
Troubleshooting
Confirm the request includes Authorization: Bearer YOUR_API_KEY, then check
whether the key was revoked or copied incorrectly.
The key needs docs:read permission to fetch /api/public/v1/docs/openapi.
Keep limit stable while paging, increase offset by the number of records
requested, and stop only when has_more is false.
API keys are organization-scoped. Create a separate key in each organization that the integration needs to access.