A TypeScript/JavaScript SDK for the OneRoster API standard - manage students, teachers, classes, enrollments, and academic data for K-12 education systems
npm install @eduware/onerosterType-safe TypeScript SDK for the OneRoster API with LMS-specific client profiles.
- OneRoster v1.1 and v1.2 support
- LMS-specific client profiles (read-only vs full CRUD)
- Custom profiles: create your own profiles with TypeScript Pick<>
- OAuth 2.0 (v1.2) and OAuth 1.0a (v1.1)
- Automatic pagination with async iterables
- TypeScript-first with comprehensive types
- Tree-shakeable standalone functions for small bundles
``bashnpm
npm add @eduware/oneroster
> Note: Yarn does not install peer dependencies automatically. Install
zod manually.Changelog
See CHANGELOG.md for release notes and breaking changes.
Quick Start (recommended)
The main entry point is the full client:
`typescript
import { OneRoster } from '@eduware/oneroster';const client = new OneRoster({
serverURL: 'https://your-oneroster-server.com',
security: {
clientID: process.env.ONEROSTER_CLIENT_ID!,
clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
tokenURL: 'https://your-oneroster-server.com/oauth/token',
},
});
const user = await client.usersManagement.getUser({
sourcedId: 'user-id',
});
const schools = await client.schoolsManagement.getAllSchools({});
for await (const page of schools) {
console.log(page.result.orgs);
}
`ClassLink Example (read-only profile)
Show LMS integrations explicitly by using the ClassLink client, which only exposes read endpoints:
`typescript
import { ClassLink } from '@eduware/oneroster/clients';const client = new ClassLink({
serverURL: 'https://example.classlink.com',
security: {
authType: 'bearer',
bearerToken: process.env.CLASSLINK_BEARER_TOKEN!,
},
});
// Read operations are available
const users = await client.usersManagement.getAllUsers({});
// Write operations are not available (TypeScript error)
// await client.usersManagement.createUser({ ... });
`Custom Profile Example (your LMS)
Define a profile that matches your LMS contract by picking only the methods you need:
`typescript
import { OneRoster } from '@eduware/oneroster';
import type { OneRosterClient } from '@eduware/oneroster/clients';
import type { UsersManagement, ClassesManagement } from '@eduware/oneroster';interface CustomProfile {
usersManagement: Pick;
classesManagement: Pick;
}
const client: OneRosterClient = new OneRoster({
serverURL: 'https://your-roster-server.com',
security: {
clientID: process.env.ONEROSTER_CLIENT_ID!,
clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
tokenURL: 'https://your-roster-server.com/oauth/token',
},
});
const users = await client.usersManagement.getAllUsers({});
`This SDK works with any OneRoster-compliant LMS and includes profiles for common integrations.
Recommended Import Path
Most users only need the main client:
`typescript
import { OneRoster } from '@eduware/oneroster';
`Operation types use
@eduware/oneroster/types:`typescript
import type { GetAllUsersUser, GetAllSchoolsOrg } from '@eduware/oneroster/types';
`Model types live at
@eduware/oneroster/models:`typescript
import type { User } from '@eduware/oneroster/models';
`Enums live at
@eduware/oneroster/enums:`typescript
import { UserRole } from '@eduware/oneroster/enums';
`Advanced import paths (standalone functions) are documented later in this README.
Client Structure
The SDK is organized by management modules, grouped by domain:
$3
-
usersManagement
- studentsManagement
- teachersManagement
- classesManagement
- coursesManagement
- enrollmentsManagement
- schoolsManagement
- organizationsManagement$3
-
academicSessionsManagement
- termsManagement
- gradingPeriodsManagement$3
-
lineItemsManagement
- resultsManagement
- categoriesManagement
- scoreScalesManagement$3
-
resourcesManagement
- courseComponentsManagement
- courseComponentResourcesManagement$3
-
assessmentLineItemsManagement
- assessmentResultsManagement$3
-
demographicsManagementCommon Operations
`typescript
// List with pagination
const users = await client.usersManagement.getAllUsers({ limit: 100 });
for await (const page of users) {
console.log(page.result.users);
}// Get by sourcedId
const student = await client.studentsManagement.getStudent({ sourcedId: 'student-id' });
// Create
await client.coursesManagement.createCourse({
course: {
title: 'Algebra I',
org: { sourcedId: 'school-id' },
},
});
// Update
await client.classesManagement.updateClass({
sourcedId: 'class-id',
class: { title: 'Math 101 - Period 2' },
});
// Delete
await client.organizationsManagement.deleteOrg({ sourcedId: 'org-id' });
`Filtering and Sorting
`typescript
import { OrderBy } from '@eduware/oneroster/enums';const activeUsers = await client.usersManagement.getAllUsers({
filter: "status='active'",
sort: 'familyName',
orderBy: OrderBy.Asc,
});
const teachers = await client.usersManagement.getAllUsers({
filter: "role='teacher' AND status='active'",
});
const searchByEmail = await client.usersManagement.getAllUsers({
search: 'teacher@district.edu',
fields: 'sourcedId,username,email',
});
`Pagination and Total Count
List operations return an async iterator. If the provider sets
X-Total-Count, it is exposed as totalCount.`typescript
const pages = await client.usersManagement.getAllUsers({ limit: 200, offset: 0 });for await (const page of pages) {
console.log('page count', page.result.users.length);
console.log('total count', page.totalCount);
}
`Nested Query Patterns
Use the module methods that reflect OneRoster relationships:
`typescript
// School -> class -> enrollments
const classes = await client.schoolsManagement.getClassesForSchool({ sourcedId: 'school-id' });
const enrollments = await client.schoolsManagement.getEnrollmentsForClassInSchool({
schoolSourcedId: 'school-id',
classSourcedId: 'class-id',
});// Teacher -> classes
const teaching = await client.teachersManagement.getClassesForTeacher({
sourcedId: 'teacher-id',
});
// Class -> line items -> results
const lineItems = await client.classesManagement.getLineItemsForClass({ sourcedId: 'class-id' });
const results = await client.classesManagement.getResultsForLineItemForClass({
classSourcedId: 'class-id',
lineItemSourcedId: 'line-item-id',
});
`OneRoster Versions
The SDK supports both OneRoster v1.1 and v1.2. Default is v1.2.
$3
`typescript
const client = new OneRoster({
serverURL: 'https://your-server.com',
security: {
clientID: process.env.ONEROSTER_CLIENT_ID!,
clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
tokenURL: 'https://your-server.com/oauth/token',
},
});
`$3
`typescript
const client = new OneRoster({
serverURL: 'https://your-server.com',
oneRosterVersion: '1.1',
security: {
authType: 'oauth1',
clientID: process.env.ONEROSTER_CLIENT_ID!,
clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
},
});
`$3
`typescript
const client = new OneRoster({
serverURL: 'https://your-server.com',
security: {
authType: 'bearer',
bearerToken: process.env.ONEROSTER_BEARER_TOKEN!,
},
});
`Error Handling
`typescript
import { OneRoster, OneRosterError, NotFoundResponseError } from '@eduware/oneroster';const client = new OneRoster({
/ ... /
});
try {
await client.usersManagement.getUser({ sourcedId: 'missing-id' });
} catch (error) {
if (error instanceof NotFoundResponseError) {
console.log('User not found');
} else if (error instanceof OneRosterError) {
console.log('HTTP Error:', error.statusCode, error.message);
}
}
`Standalone Functions (tree-shaking)
Use standalone functions for minimal bundles or serverless environments:
`typescript
import { OneRosterCore } from '@eduware/oneroster/core.js';
import { usersManagementGetAllUsers } from '@eduware/oneroster/funcs/usersManagementGetAllUsers.js';const core = new OneRosterCore({
security: {
clientID: process.env.ONEROSTER_CLIENT_ID!,
clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
},
});
const result = await usersManagementGetAllUsers(core, {});
if (result.ok) {
for await (const page of result.value) {
console.log(page.result.users);
}
}
`See FUNCTIONS.md for the full list.
Function Index (by Module)
Each function maps to
@eduware/oneroster/funcs/.$3
`text
academicSessionsManagementDeleteAcademicSession
academicSessionsManagementGetAcademicSession
academicSessionsManagementGetAllAcademicSessions
academicSessionsManagementPostAcademicSession
academicSessionsManagementPutAcademicSession
`$3
`text
assessmentLineItemsManagementCreateAssessmentLineItem
assessmentLineItemsManagementDeleteAssessmentLineItem
assessmentLineItemsManagementGetAllAssessmentLineItems
assessmentLineItemsManagementGetAssessmentLineItem
assessmentLineItemsManagementUpdateAssessmentLineItem
`$3
`text
assessmentResultsManagementCreateAssessmentResult
assessmentResultsManagementDeleteAssessmentResult
assessmentResultsManagementGetAllAssessmentResults
assessmentResultsManagementGetAssessmentResult
assessmentResultsManagementUpdateAssessmentResult
`$3
`text
categoriesManagementCreateCategory
categoriesManagementDeleteCategory
categoriesManagementGetAllCategories
categoriesManagementGetCategory
categoriesManagementUpdateCategory
`$3
`text
classesManagementAddStudentToClass
classesManagementAddTeacherToClass
classesManagementCreateClass
classesManagementDeleteClass
classesManagementGetAllClasses
classesManagementGetCategoriesForClass
classesManagementGetClass
classesManagementGetClassesForStudent
classesManagementGetClassesForTeacher
classesManagementGetClassesForTerm
classesManagementGetClassesForUser
classesManagementGetLineItemsForClass
classesManagementGetResultsForClass
classesManagementGetResultsForLineItemForClass
classesManagementGetResultsForStudentForClass
classesManagementGetScoreScalesForClass
classesManagementGetStudentsForClass
classesManagementGetTeachersForClass
classesManagementPostResultsForAcademicSessionForClass
classesManagementUpdateClass
`$3
`text
coursesManagementCreateComponentResource
coursesManagementCreateCourse
coursesManagementCreateCourseComponent
coursesManagementDeleteComponentResource
coursesManagementDeleteCourse
coursesManagementDeleteCourseComponent
coursesManagementGetAllComponentResources
coursesManagementGetAllCourseComponents
coursesManagementGetAllCourses
coursesManagementGetClassesForCourse
coursesManagementGetComponentResource
coursesManagementGetCourse
coursesManagementGetCourseComponent
coursesManagementPutComponentResource
coursesManagementPutCourse
coursesManagementPutCourseComponent
`$3
`text
demographicsManagementDeleteDemographics
demographicsManagementGetAllDemographics
demographicsManagementGetDemographics
demographicsManagementPostDemographics
demographicsManagementPutDemographics
`$3
`text
enrollmentsManagementCreateEnrollment
enrollmentsManagementDeleteEnrollment
enrollmentsManagementGetAllEnrollments
enrollmentsManagementGetEnrollment
enrollmentsManagementUpdateEnrollment
`$3
`text
gradingPeriodsManagementCreateGradingPeriod
gradingPeriodsManagementDeleteGradingPeriod
gradingPeriodsManagementGetAllGradingPeriods
gradingPeriodsManagementGetGradingPeriod
gradingPeriodsManagementUpdateGradingPeriod
`$3
`text
lineItemsManagementCreateLineItem
lineItemsManagementCreateResultForLineItem
lineItemsManagementDeleteLineItem
lineItemsManagementGetAllLineItems
lineItemsManagementGetLineItem
lineItemsManagementUpdateLineItem
`$3
`text
organizationsManagementCreateOrg
organizationsManagementDeleteOrg
organizationsManagementGetAllOrgs
organizationsManagementGetOrg
organizationsManagementUpdateOrg
`$3
`text
resourcesManagementCreateResource
resourcesManagementDeleteResource
resourcesManagementExportResourceToCommonCartridge
resourcesManagementGetAllResources
resourcesManagementGetResource
resourcesManagementGetResourcesForClass
resourcesManagementGetResourcesForCourse
resourcesManagementGetResourcesForUser
resourcesManagementUpdateResource
`$3
`text
resultsManagementCreateResult
resultsManagementDeleteResult
resultsManagementGetAllResults
resultsManagementGetResult
resultsManagementUpdateResult
`$3
`text
schoolsManagementCreateLineItemsForSchool
schoolsManagementCreateSchool
schoolsManagementDeleteSchool
schoolsManagementGetAllSchools
schoolsManagementGetClassesForSchool
schoolsManagementGetCoursesForSchool
schoolsManagementGetEnrollmentsForClassInSchool
schoolsManagementGetEnrollmentsForSchool
schoolsManagementGetLineItemsForSchool
schoolsManagementGetSchool
schoolsManagementGetStudentsForClassInSchool
schoolsManagementGetStudentsForSchool
schoolsManagementGetTeachersForClassInSchool
schoolsManagementGetTeachersForSchool
schoolsManagementGetTermsForSchool
schoolsManagementUpdateSchool
`$3
`text
scoreScalesManagementCreateScoreScale
scoreScalesManagementDeleteScoreScale
scoreScalesManagementGetAllScoreScales
scoreScalesManagementGetScoreScale
scoreScalesManagementGetScoreScalesForSchool
scoreScalesManagementUpdateScoreScale
`$3
`text
studentsManagementGetAllStudents
studentsManagementGetStudent
`$3
`text
teachersManagementGetAllTeachers
teachersManagementGetTeacher
`$3
`text
termsManagementCreateGradingPeriodForTerm
termsManagementGetAllTerms
termsManagementGetGradingPeriodsForTerm
termsManagementGetTerm
`$3
`text
usersManagementCreateUser
usersManagementDeleteUser
usersManagementGetAllUsers
usersManagementGetUser
usersManagementGetUserWithDemographics
usersManagementUpdateUser
`LMS Provider Support
Support varies by LMS provider and contract. The profile you choose reflects LMS capabilities, not library limitations.
$3
| Provider | Profile | Notes |
| --------- | ----------- | -------------------------- |
| OneRoster | full | All endpoints available |
| ClassLink | classlink | Read-only rostering access |
| (future) | coming soon | Add new LMS profiles here |
$3
| Module | Create | Read | Update | Delete |
| ------------------------------------ | :----: | :--: | :----: | :----: |
|
usersManagement | ✅ | ✅ | ✅ | ✅ |
| studentsManagement | — | ✅ | — | — |
| teachersManagement | — | ✅ | — | — |
| classesManagement | ✅ | ✅ | ✅ | ✅ |
| coursesManagement | ✅ | ✅ | ✅ | ✅ |
| enrollmentsManagement | ✅ | ✅ | ✅ | ✅ |
| schoolsManagement | ✅ | ✅ | ✅ | ✅ |
| organizationsManagement | ✅ | ✅ | ✅ | ✅ |
| academicSessionsManagement | ✅ | ✅ | ✅ | ✅ |
| termsManagement | — | ✅ | — | — |
| gradingPeriodsManagement | ✅ | ✅ | ✅ | ✅ |
| demographicsManagement | ✅ | ✅ | ✅ | ✅ |
| lineItemsManagement | ✅ | ✅ | ✅ | ✅ |
| resultsManagement | ✅ | ✅ | ✅ | ✅ |
| categoriesManagement | ✅ | ✅ | ✅ | ✅ |
| scoreScalesManagement | ✅ | ✅ | ✅ | ✅ |
| resourcesManagement | ✅ | ✅ | ✅ | ✅ |
| courseComponentsManagement | ✅ | ✅ | ✅ | ✅ |
| courseComponentResourcesManagement | ✅ | ✅ | ✅ | ✅ |
| assessmentLineItemsManagement | ✅ | ✅ | ✅ | ✅ |
| assessmentResultsManagement | ✅ | ✅ | ✅ | ✅ |_Note: — indicates the module uses parent module operations (students/teachers map to usersManagement for create/update/delete)._
$3
| Module | OneRoster (Full) | ClassLink |
| ------------------------------------ | :--------------: | :-------: |
|
usersManagement | ✅ CRUD | ✅ Read |
| studentsManagement | ✅ Read | ✅ Read |
| teachersManagement | ✅ Read | ✅ Read |
| classesManagement | ✅ CRUD | ✅ Read |
| coursesManagement | ✅ CRUD | ✅ Read |
| enrollmentsManagement | ✅ CRUD | ✅ Read |
| schoolsManagement | ✅ CRUD | ✅ Read |
| organizationsManagement | ✅ CRUD | ✅ Read |
| academicSessionsManagement | ✅ CRUD | ✅ Read |
| termsManagement | ✅ Read | ✅ Read |
| gradingPeriodsManagement | ✅ CRUD | ✅ Read |
| demographicsManagement | ✅ CRUD | ❌ |
| lineItemsManagement | ✅ CRUD | ❌ |
| resultsManagement | ✅ CRUD | ❌ |
| categoriesManagement | ✅ CRUD | ❌ |
| scoreScalesManagement | ✅ CRUD | ❌ |
| resourcesManagement | ✅ CRUD | ❌ |
| courseComponentsManagement | ✅ CRUD | ❌ |
| courseComponentResourcesManagement | ✅ CRUD | ❌ |
| assessmentLineItemsManagement | ✅ CRUD | ❌ |
| assessmentResultsManagement | ✅ CRUD | ❌ |> This matrix reflects typical provider behavior. Actual availability may vary by contract or configuration.
Advanced Import Paths
Use these only when you need them.
$3
`text
@eduware/oneroster # Full client + common exports (recommended)
@eduware/oneroster/clients # LMS profiles (ClassLink, custom profiles)
@eduware/oneroster/core.js # Lightweight core client for funcs
@eduware/oneroster/funcs/* # Standalone functions
`$3
`text
@eduware/oneroster/models # Data models (component schemas)
@eduware/oneroster/enums # Shared enums (runtime + types)
@eduware/oneroster/types # Operation request/response types (runtime alias)
`MCP Server
This SDK includes an MCP (Model Context Protocol) server for AI applications.
$3
`json
{
"mcpServers": {
"OneRoster": {
"command": "npx",
"args": [
"-y",
"--package",
"@eduware/oneroster",
"--",
"mcp",
"start",
"--server-url",
"https://your-oneroster-server.com",
"--client-id",
"your-client-id",
"--client-secret",
"your-client-secret",
"--token-url",
"https://your-server.com/oauth/token"
]
}
}
}
`$3
`json
{
"mcpServers": {
"OneRoster": {
"command": "npx",
"args": [
"-y",
"--package",
"@eduware/oneroster",
"--",
"mcp",
"start",
"--server-url",
"https://oneroster-proxy.apis.classlink.com/YOUR_TENANT_ID",
"--auth-type",
"bearer",
"--bearer-token",
"your-bearer-token",
"--client-profile",
"classlink"
]
}
}
}
`$3
`json
{
"mcpServers": {
"OneRoster": {
"command": "npx",
"args": [
"-y",
"--package",
"@eduware/oneroster",
"--",
"mcp",
"start",
"--server-url",
"https://your-oneroster-server.com",
"--auth-type",
"oauth1",
"--oneroster-version",
"1.1",
"--client-id",
"your-client-id",
"--client-secret",
"your-client-secret"
]
}
}
}
`$3
| Argument | Description | Default | Required |
| --------------------- | ------------------------------------------------------------- | --------- | ----------------- |
|
--server-url | OneRoster API server URL | — | Yes |
| --auth-type | Authentication type: oauth1, oauth2, or bearer | oauth2 | No |
| --client-id | OAuth client ID | — | For oauth1/oauth2 |
| --client-secret | OAuth client secret | — | For oauth1/oauth2 |
| --token-url | OAuth 2.0 token endpoint URL | — | For oauth2 |
| --bearer-token | Pre-authenticated bearer token | — | For bearer |
| --client-profile | Client profile: full (all tools) or classlink (read-only) | full | No |
| --oneroster-version | OneRoster API version: 1.1 or 1.2 | 1.2 | No |
| --transport | Transport protocol: stdio or sse | stdio | No |
| --port | Port for SSE transport | 2718 | No |
| --tool | Specific tools to mount (repeatable) | All tools | No |
| --log-level | Log level: debug, info, warn, error | info | No |
| --env | Environment variables (format: KEY=value`, repeatable) | — | No |See FUNCTIONS.md for the full method list.
MIT