---
name: iblai-connect-oneroster
description: "Read and write 1EdTech OneRoster data through the OneRoster 1.2 Rostering, Gradebook and Resources services (REST and CSV bindings) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with 1EdTech OneRoster data, or to set up a 1EdTech OneRoster MCP connection on ibl.ai."
metadata:
  kind: guide
---

# 1EdTech OneRoster connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/oneroster — not part of the iblai/vibe repository. Checked against 1EdTech's documentation on October 20, 2026; test it against your own 1EdTech OneRoster setup before you rely on it.

OneRoster is 1EdTech's standard for exchanging rosters and grades between student information systems, learning platforms and apps: orgs, users, courses, classes, enrollments, academic sessions, line items, results and resources.

## Auth & conventions

- **API:** OneRoster 1.2 Rostering, Gradebook and Resources services (REST and CSV bindings) (Mixed). Three services: Rostering (GET only), Gradebook (line items, results, categories, score scales, assessment items; create, update, delete) and Resources. REST binding for live calls; CSV binding is a zip of CSV files with manifest.csv.
- **Base URL:** https://{provider-host}/ims/oneroster/rostering/v1p2/ (gradebook: /ims/oneroster/gradebook/v1p2/)
- **Access:** Issued by your administrator. The specification is public. Credentials come from each data provider (an SIS or rostering hub) at the school or district's direction. 1EdTech certifies conforming products.
- **Auth:** OAuth 2.0 client credentials (v1.2); OAuth 1.0a (v1.1, deprecated). 1.2 requires TLS and OAuth 2.0 client-credentials bearer tokens. Scopes include .../scope/roster.readonly, roster-core.readonly, gradebook.readonly, gradebook.createput and gradebook.delete (prefix https://purl.imsglobal.org/spec/or/v1p2).
- **Limits:** Paging uses limit (default 100) and offset (default 0); responses carry X-Total-Count and Link headers. Query parameters filter, sort, orderBy and fields shape results.
- Keep 1EdTech OneRoster credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Orgs and schools** — Rostering service org and school endpoints under /ims/oneroster/rostering/v1p2.
- **Users, students and teachers** — User records; demographics need the roster-demographics.readonly or roster.readonly scope.
- **Classes and enrollments** — e.g. GET /classes/{sourcedId}/students and /schools/{id}/classes/{id}/enrollments.
- **Academic sessions and courses** — GET /academicSessions and course endpoints for terms, grading periods and courses.
- **Line items and results** — Gradebook service /lineItems, /results, /categories, /scoreScales (gradebook.readonly).
- **Resources** — Resource service: descriptions of resources assigned to classes, courses and users (not access to them).

## Writes

- **Line items and categories** — PUT/POST on gradebook /lineItems, /categories, /scoreScales (gradebook.createput).
- **Results (scores)** — PUT/POST on /results writes student scores to the provider's gradebook (gradebook.createput). **Confirm with the user first.**
- **Gradebook deletions** — DELETE on line items, results and related objects (gradebook.delete). **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

1EdTech did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Connect to our district's OneRoster 1.2 endpoint and list all classes for the current term"
- "Pull enrollments for every class at Jefferson High using filter and paging"
- "Write these unit-test scores as OneRoster results for the matching line items"
- "Validate this OneRoster CSV zip and tell me which files or columns are missing"

## Guardrails

- Data exchanged is student education records protected by FERPA (in the U.S.): identities, demographics, enrollments and grades. The standard defines the format, not who may see it.
- Request the narrowest 1EdTech OneRoster scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- 1EdTech OneRoster standard: https://www.1edtech.org/standards/oneroster
- OneRoster 1.2 specification: https://www.imsglobal.org/spec/oneroster/v1p2
- OneRoster 1.2 Rostering REST binding: https://www.imsglobal.org/spec/oneroster/v1p2/rostering/bind/rest
- This connector on ibl.ai: https://ibl.ai/developer/connectors/oneroster
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections