Home / Developer docs
API explorer OpenAPI spec

Developer docs

Build OneRoster integrations with district-controlled data access.

OpenRoster gives application vendors a standards-based API for roster data while districts approve exactly which tenants, schools, roles, fields, and masked attributes an app can use.

Start building Try a live request

client_credentials

curl https://api.openroster.org/auth/token/tenant_123 \
  -u "$OPENROSTER_CLIENT_ID:$OPENROSTER_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=https://purl.imsglobal.org/spec/or/rostering.readonly"

curl https://api.openroster.org/ims/oneroster/rostering/v1p2/users \
  -H "Authorization: Bearer $OPENROSTER_TOKEN" \
  -H "Accept: application/json"

App catalog

Register vendor apps, publish integration details, and make the app discoverable for district administrators.

District grants

Ask a district for the specific schools, roles, entities, attributes, and delivery windows needed by the app.

Roster exchange

Read 1EdTech OneRoster 1.2 data through a tenant-scoped REST API backed by synchronized district source data.

Privacy controls

Respect district policy through field-level permissions, context filters, and masked attributes for sensitive data.

Quickstart

Create your first integration

Start in a sandbox, register an app, declare the data your product needs, and use the explorer to validate the same request shape you will use in production.

  1. 1

    Create a vendor account and app

    Add the application name, support contacts, privacy policy, integration type, and requested OneRoster version.

  2. 2

    Request district data access

    Choose the schools, entities, fields, masking rules, and filters needed to run the product.

  3. 3

    Exchange credentials for a tenant token

    Each token is tied to a tenant, app, version, scope set, and approved grant.

  4. 4

    Read OneRoster resources

    Call the rostering API and handle pagination, filtering, masked attributes, and permission-aware empty responses.

Token endpoint
POST /auth/token/{tenantId}
Authorization: Basic base64(client_id:secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
scope=https://purl.imsglobal.org/spec/or/rostering.readonly

Use the hosted explorer for live calls

Credentials are submitted to same-origin helper routes and are not stored in browser storage.

Open explorer

Sandbox

Test from both sides of the exchange

Like mature education data platforms, OpenRoster’s sandbox workflow should let vendors see the app side and districts see the approval side before either party touches production data.

Vendor sandbox

Create an app, set data requirements, request district access, accept consents, browse synced data, and test API calls.

District sandbox

Import roster data, review app requests, choose schools and attributes, enable masking, and approve or reject grants.

Integration test

Run sync scenarios, verify OneRoster payloads, check data quality, and confirm the app handles masked or filtered records.

Workflows

Vendor and district responsibilities

App developer workflow

  1. 1 Create a vendor organization and register each application in the OpenRoster admin app.
  2. 2 Declare requested OneRoster versions, entities, attributes, context filters, and launch or sync needs.
  3. 3 Use sandbox credentials first, then request district approval for production tenants.
  4. 4 Exchange the client ID and secret for a tenant-scoped OAuth client-credentials token.
  5. 5 Call the OneRoster API; OpenRoster applies the district grant, field rules, context filters, and masking.

District workflow

  1. 1 Connect the district roster source and validate sync health.
  2. 2 Review each vendor app request by entity, field, masked field, audience, school, course, class, and term context.
  3. 3 Approve the least data needed for the product use case, with demographics separated from ordinary roster data.
  4. 4 Rotate or revoke credentials when contracts, schools, or implementation status change.
  5. 5 Monitor live token and endpoint behavior through scoped test calls before go-live.

Data access and flow

  1. 1 Roster data lands in a tenant-owned data store and remains isolated by tenant ID.
  2. 2 Vendor credentials are bound to an app, tenant, API version, and approved scope set.
  3. 3 Every API request is authorized by the token, then narrowed by entity permissions, fields, context, and masking.
  4. 4 Responses follow the 1EdTech OneRoster REST shapes so vendors can integrate once across districts.
  5. 5 No explorer credential is persisted by the public docs; token and request helpers run through same-origin server routes.

Data access

District approval controls the data plane

An app can be published without receiving production data. A district grant is what connects the app to a tenant and defines the exact data shape returned by the API.

Schools

District-selected orgs and school contexts exposed to the app.

Attributes

Included or excluded fields for users, classes, courses, enrollments, sessions, and demographics.

Filters

Rules that limit shared records by school, course, class, role, grade, term, or implementation scope.

Masking

Approved attributes can be transformed before the vendor receives the response.

Delivery

REST API access is tenant-scoped; future delivery modes can follow the same grant policy.

Request lifecycle

1. Source data syncs into the tenant

Roster records stay isolated by district tenant.

2. Grant policy is evaluated

The app, tenant, scope, route, fields, and filters are checked.

3. Response is shaped

Records are filtered and sensitive attributes are omitted or masked.

OneRoster API

Standards-based rostering

OpenRoster documents the 1EdTech OneRoster 1.2 REST shape and exposes supported rostering endpoints through the OpenAPI reference and API explorer.

Academic sessionsOrganizationsUsersCoursesClassesEnrollmentsDemographics
GET /ims/oneroster/rostering/v1p2/classes
{
  "classes": [
    {
      "sourcedId": "class-ela-10-01",
      "status": "active",
      "title": "English Language Arts 10",
      "classCode": "ELA10-01",
      "classType": "scheduled",
      "school": { "sourcedId": "school-101", "type": "org" }
    }
  ]
}

Privacy masking

Protect sensitive attributes by default

Districts can approve the minimum useful data for a product while masking or removing attributes that are not needed. Vendors should treat masked values as normal API output and avoid depending on raw personally identifiable data.

Masking flow
  1. Vendor marks sensitive requested fields.
  2. District reviews and approves the grant.
  3. OpenRoster applies the policy at request time.
  4. The API returns the allowed OneRoster response shape.

Test integration

Use the API explorer as the integration workbench

Run tenant-scoped requests with live credentials, switch role lenses, inspect scopes, compare sample payloads, and validate district grant behavior before go-live.

Open API explorer

Certification

Production readiness checklist

Certification gives districts confidence that an app handles roster data securely, works with OneRoster responses, and follows least-data access expectations.

  1. Step 1 Prepare: confirm requested scopes, data requirements, security posture, and district-facing app details.
  2. Step 2 Submit: provide the integration profile, privacy notes, test tenant, and support contacts.
  3. Step 3 Evaluate: run technical checks for authentication, grant enforcement, OneRoster compatibility, and error handling.
  4. Step 4 Launch: publish the app for production districts and monitor sync health, token usage, and support issues.

API reference

OpenAPI reference

Download OpenAPI

OpenAPI reference

1EdTech OneRoster 1.2 endpoints

Download JSON