Chalk

Docs · API reference

OneRoster API

Once Chalk has your district's roster, every downstream app can consume it the same way. The Chalk hosted service exposes a read-only OneRoster 1.1 REST API under /api/oneroster/v1p1/.

Authentication

Every request must include a bearer token issued by the Chalk admin console. Tokens are scoped to a single tenant.

Generate a token

  1. Sign in to the admin console as a tenant administrator.
  2. Navigate to /settings/api-tokens.
  3. Click Generate token, give it a descriptive label, and copy the value. The token is shown once and stored hashed; if you lose it, revoke and regenerate.

Tokens are prefixed chk_ so they're easy to spot in logs and secret scanners.

Send the token

Send the token in the Authorization header on every request:

Authorization: Bearer chk_live_5f8a2c9d4e7b1a3f6c8e2d4b9a7f1e3c

Base URL

All endpoints live under your tenant's hosted Chalk instance: 

https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/<resource>

Self-hosted instances expose the same paths under the host you configured.

Response envelope

All collection responses are wrapped in a JSON object keyed by the resource name. Individual responses use the singular form. 

{
  "users": [
    {
      "sourcedId": "u-1234",
      "status": "active",
      "role": "student",
      "givenName": "Ada",
      "familyName": "Lovelace",
      "email": "ada.lovelace@example.edu"
    }
  ]
}

Pagination

Pagination is not yet finalized. Today, collection endpoints return the full tenant set in a single response. A cursor-based pagination scheme using limit and offset query parameters (per the OneRoster 1.1 spec) is on the roadmap; until then, prefer the webhook stream for change tracking.

Endpoints

All endpoints respond to GET and return application/json.

GET /api/oneroster/v1p1/orgs

Districts, schools, and other organizational units in the canonical roster.

Envelope

{ "orgs": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/orgs
GET /api/oneroster/v1p1/academicSessions

School years, terms, semesters, and grading periods.

Envelope

{ "academicSessions": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/academicSessions
GET /api/oneroster/v1p1/users

Students, teachers, administrators, and staff with their identifiers and roles.

Envelope

{ "users": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/users
GET /api/oneroster/v1p1/courses

Course catalog entries (the abstract course, not a scheduled class).

Envelope

{ "courses": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/courses
GET /api/oneroster/v1p1/classes

Scheduled class sections tied to a course, term, and school.

Envelope

{ "classes": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/classes
GET /api/oneroster/v1p1/enrollments

Student-to-class and teacher-to-class assignments with active dates.

Envelope

{ "enrollments": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/enrollments
GET /api/oneroster/v1p1/demographics

Optional demographic attributes for users (only populated when the district opts in).

Envelope

{ "demographics": [ ... ] }

Example

curl -H "Authorization: Bearer chk_live_…" \
  https://<your-workspace>.usechalk.xyz/api/oneroster/v1p1/demographics

Errors

Errors are returned as JSON with an error code and human-readable message.

Status Code When
401 invalid_token Missing, malformed, expired, or revoked bearer token.
500 server_error Unexpected error on the Chalk side. Retry with backoff; if persistent, contact support. 
{
  "error": "invalid_token",
  "message": "The bearer token is missing or invalid."
}

Rate limits

There is no per-token rate limit at this time. We may introduce per-token quotas in the future; if we do, we will advertise the limit via X-RateLimit-* response headers and announce the change to tenant administrators ahead of the rollout. In the meantime, please be a good neighbor — cache when you can and use webhooks for change-driven workflows.

Need help?

See the getting-started guide for a first-admin walkthrough, or contact support if something looks off.