---
name: timeback-oneroster-1edtech
description: Use when building apps, reports, QA checks, or deliverables against the platform3 OneRoster 1EdTech surface. The skill gives AI agents endpoint, auth, source-of-truth, and worked-example instructions for calling the live TimeBack OneRoster API without reimplementing OneRoster validation, schema parsing, deduplication, tenancy, idempotency, ETags, score-scale, or privacy logic.
---

# TimeBack OneRoster 1EdTech

Use this skill when you need to build something against the TimeBack platform3 OneRoster 1EdTech surface: a SIS-style app, integration report, smoke check, import/export workflow, or customer deliverable.

This skill is instructions only. It must not carry OneRoster business logic. The live surface owns validation, tenant isolation, idempotency, ETags, typed Problems, import/export evidence, allowed values, and score-scale behavior.

## Install This Pack

Set the pack URL once:

```bash
export PACK_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/skill_pack"
```

Claude Code user-level install:

```bash
export CLAUDE_SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/timeback-oneroster-1edtech}"
mkdir -p "$CLAUDE_SKILL_DIR/references" "$CLAUDE_SKILL_DIR/agents"
curl -fsS "$PACK_URL/pack/SKILL.md" -o "$CLAUDE_SKILL_DIR/SKILL.md"
curl -fsS "$PACK_URL/pack/references/worked-example.md" -o "$CLAUDE_SKILL_DIR/references/worked-example.md"
curl -fsS "$PACK_URL/pack/references/runnable-check.md" -o "$CLAUDE_SKILL_DIR/references/runnable-check.md"
curl -fsS "$PACK_URL/pack/references/source-contract.md" -o "$CLAUDE_SKILL_DIR/references/source-contract.md"
curl -fsS "$PACK_URL/pack/agents/claude.yaml" -o "$CLAUDE_SKILL_DIR/agents/claude.yaml"
```

For a workspace-scoped Claude install, use `.claude/skills/timeback-oneroster-1edtech/` as `CLAUDE_SKILL_DIR`.

Codex CLI install:

```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export CODEX_SKILL_DIR="$CODEX_HOME/skills/timeback-oneroster-1edtech"
mkdir -p "$CODEX_SKILL_DIR/references" "$CODEX_SKILL_DIR/agents"
curl -fsS "$PACK_URL/pack/SKILL.md" -o "$CODEX_SKILL_DIR/SKILL.md"
curl -fsS "$PACK_URL/pack/references/worked-example.md" -o "$CODEX_SKILL_DIR/references/worked-example.md"
curl -fsS "$PACK_URL/pack/references/runnable-check.md" -o "$CODEX_SKILL_DIR/references/runnable-check.md"
curl -fsS "$PACK_URL/pack/references/source-contract.md" -o "$CODEX_SKILL_DIR/references/source-contract.md"
curl -fsS "$PACK_URL/pack/agents/openai.yaml" -o "$CODEX_SKILL_DIR/agents/openai.yaml"
curl -fsS "$PACK_URL/pack/agents/codex.yaml" -o "$CODEX_SKILL_DIR/agents/codex.yaml"
```

Perplexity Computer import workaround:

```bash
export PERPLEXITY_PACK_DIR="$HOME/perplexity-computer/skills/timeback-oneroster-1edtech"
mkdir -p "$PERPLEXITY_PACK_DIR/references" "$PERPLEXITY_PACK_DIR/agents"
curl -fsS "$PACK_URL/pack/SKILL.md" -o "$PERPLEXITY_PACK_DIR/SKILL.md"
curl -fsS "$PACK_URL/pack/references/worked-example.md" -o "$PERPLEXITY_PACK_DIR/references/worked-example.md"
curl -fsS "$PACK_URL/pack/references/runnable-check.md" -o "$PERPLEXITY_PACK_DIR/references/runnable-check.md"
curl -fsS "$PACK_URL/pack/references/source-contract.md" -o "$PERPLEXITY_PACK_DIR/references/source-contract.md"
curl -fsS "$PACK_URL/pack/agents/perplexity.md" -o "$PERPLEXITY_PACK_DIR/agents/perplexity.md"
```

Attach the downloaded folder to the Perplexity Computer project and paste the opening description of this `SKILL.md` as the project instruction. If that host later exposes a native filesystem skill loader, copy the same folder into that loader.

## Source Of Truth

Use the hosted docs before making claims:

- Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/customer_website
- Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary
- Architecture decisions: https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/architecture
- Live API base URL: https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/implementation/api
- Surface QC: https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/surface_qc

When you need exact operations, fetch the customer website contract instead of inventing routes:

```bash
curl -fsS https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/customer_website/contract.json
```

When you need field meaning, nullability, ranges, allowed values, or provenance, read the data dictionary. Do not copy field tables into your own code or prompt context unless the user's task requires quoting a small portion.

## Credentials

Use one live base URL for demo and real tenants:

```bash
export ONEROSTER_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/implementation/api"
export BASE_URL="$ONEROSTER_BASE_URL"
```

For demo work, mint a token from the surface:

```bash
export ONEROSTER_DEMO_JWT="$(curl -fsS -X POST "$ONEROSTER_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"
curl -fsS "$ONEROSTER_BASE_URL/classes" -H "Authorization: Bearer $ONEROSTER_DEMO_JWT"
```

If `jq` is unavailable, call the mint endpoint and copy the returned `token` string into `ONEROSTER_DEMO_JWT`.

For real tenant or reviewer work, use the operator-provided JWT, usually `ONEROSTER_REVIEWER_JWT`, on the same `ONEROSTER_BASE_URL`:

```bash
curl -fsS "$ONEROSTER_BASE_URL/academicSessions" -H "Authorization: Bearer $ONEROSTER_REVIEWER_JWT"
```

Do not expose a real-tenant token mint endpoint. The public mint endpoint is demo-only.

## Workflow

1. Read the customer website quickstart and the data dictionary entries for the resources you will touch.
2. Fetch `contract.json` if you need route coverage. Treat it as the operation list.
3. Acquire a demo token or use the provided real-tenant JWT.
4. Build by calling the surface. Store domain data through the surface. Use browser storage only for app UI state.
5. For writes, send `Idempotency-Key`. For updates and deletes, read the resource first and send the returned `ETag` as `If-Match`.
6. Handle typed RFC 7807 Problems by branching on `code`, not by scraping free text.
7. When proof is needed, run `references/runnable-check.md` and cite its output rather than inventing a local verification path.
8. Cite the canonical docs and the exact API calls you used in any report or generated deliverable.

## Surface-Owned Logic Boundary

Stop and report a surface leak if your task appears to require any of these inside your app, report, or agent code:

- parsing OneRoster CSV schemas or maintaining a local schema map;
- copying allowed-value tables, score-scale rules, dependency matrices, or validation rules;
- deduplicating imports, replaying idempotency, or detecting duplicate writes yourself;
- calculating ETags or bypassing `If-Match`;
- deciding tenant visibility outside the JWT claims;
- transforming OneRoster into an Alpha or school-language vocabulary;
- redacting PII from Problem details or audit records yourself.

Correct behavior is to call the surface, read the returned Problem or resource, and point back to the relevant hosted doc.

## Common Calls

Use these as route-shape examples, then fetch `contract.json` for the complete operation set:

```bash
curl -fsS "$BASE_URL/orgs/school-north-valley" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/classes/class-algebra-1-a" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/users/student-maya-johnson" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/enrollments/enrollment-maya-algebra-1-a" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/lineItems/lineitem-algebra-quiz-1" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/classes/class-algebra-1-a/students" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/classes/class-algebra-1-a/lineItems" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/users/student-maya-johnson/enrollments" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/users/student-maya-johnson/results" -H "Authorization: Bearer $TOKEN"
curl -fsS "$BASE_URL/results/result-maya-algebra-quiz-1" -H "Authorization: Bearer $TOKEN"
```

Export a OneRoster CSV package:

```bash
curl -fsS -X POST "$BASE_URL/exports/csv" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-$(date +%s)" \
  -d '{"mode":"bulk"}'
```

Import a CSV package by posting a multipart `package` field to `/imports/csv` with an `Idempotency-Key`. The surface owns validation and batch evidence.

## References

Read these bundled references only when needed:

- `references/worked-example.md` - end-to-end demo workflow that produces a roster and grade-evidence report from live surface calls.
- `references/runnable-check.md` - copy-paste probe that verifies the platform's pinned demo answers from live surface responses.
- `references/source-contract.md` - canonical doc links, route guidance, Problem handling, and leak-check details.