TimeBack Partner API · Product Overview

Plug your learning app into a student's day.

A plain-English guide for product managers planning a TimeBack integration — what it unlocks, what you own, what Alpha owns, and exactly how much you need to build.

For the engineering reference, see your partner bundle's getting-started.html and the Scalar API reference.

What TimeBack is, in one minute

TimeBack is the learning platform behind Alpha Schools, where students master core academics in roughly two hours per day through personalized, adaptive learning. To make that work, TimeBack tracks what each student is doing, how well they're doing it, and whether they're progressing against grade-level expectations — across every app and every subject.

If you're building an app that students use as part of their learning day, TimeBack is the system of record for who those students are, what they're working on, what they did in your app, and how much credit they earned. You plug your app in so the student's activity counts toward their day.

★

What you get out of integrating

  • Your app's time and outcomes count toward a student's daily goal.
  • Parents, guides, and admins see your app's contribution alongside every other app they use.
  • You can optionally offer "Sign in with TimeBack" — the same way you might offer "Sign in with Google" — so Alpha students don't need a separate account in your app.
  • You can read back aggregated analytics for your students without building a data pipeline.

The vocabulary you'll need

Seven concepts cover most conversations. Learn these and the technical docs read smoothly.

Student (a user)

A learner in TimeBack. Has a stable ID (sourcedId), a grade level, and a home school. The person your app is serving.

School (an org)

Where the student attends. Each student carries their school's sourcedId, and your API calls pick it up from the student's record when needed — you don't have to maintain a list of participating schools yourself. In staging, you get a sandbox org called partner-sandbox so you can test without a real school.

Course

A top-level body of content your app teaches — e.g. "AlphaTok: Middle-School Reading." A course is how you register a track of content with TimeBack. You own your courses.

Unit & Lesson

The internal structure of your course. A course contains units; a unit contains lessons. A lesson is the reporting grain — the smallest bucket you want student activity summarized at. You own these too.

Class

A specific offering of a course that students get enrolled into. Alpha staff create classes and enrollments as they assign students to your app. You don't create classes in production.

Event (a Caliper event)

A message you send when something meaningful happens in your app: a student started a lesson, answered a question, finished an assignment, earned XP. Events are the heartbeat of your integration — everything downstream (XP, analytics, dashboards) is derived from them.

XP (experience points)

The universal currency of productive learning in TimeBack. Next section.

XP, explained

XP is how TimeBack measures whether a student had a productive learning day. 1 XP is approximately 1 minute of productive, on-task learning effort. A student's day is typically described as "2,500 XP earned" or "goal met" — not hours or lessons completed.

!

The single most important integration detail

Every graded event you send must reference the course and lesson it belongs to, via extensions.course.id and extensions.lesson.id. That's how TimeBack credits the right enrollment and reports activity at the right grain. Events without these are dropped at ingestion — no XP, no analytics.

Who owns what: you vs. Alpha

A recurring source of confusion: some objects in TimeBack are owned by you (the partner), some by Alpha, and some are derived automatically. Here's the cut:

ObjectWho creates it in productionWhy
Courses You A course is your content catalog. Only you know what's in your app.
Units & Lessons You The structure inside your course. Lessons define your reporting grain.
Events You Only you know what's happening inside your app.
Students (users) Alpha Alpha rosters students into schools. You receive them.
Schools (orgs) Alpha Alpha signs agreements with schools. You're told which to use.
Classes Alpha A class is a specific cohort assigned to your app. Alpha decides which students get your app.
Enrollments Alpha Same — Alpha picks which students to assign.
XP, analytics, gradebook results Derived Never written directly. Always computed from the events you sent.

In steady-state production, you're writing two things: your content catalog (rarely — when your app changes) and Caliper events (constantly — every meaningful student action). Everything else you read.

The integration

There's one integration shape. Every partner does all four of these. Pick them up in order.

  1. Publish your content catalog

    Once per course you want students working in, and whenever your content changes: register the course, its units, and its lessons. Pick your lesson grain carefully — a lesson is the smallest bucket you want activity reported on (per video, per problem set, per game mode, per skill). You can't get finer-grained reporting than the lesson level you publish.

    PUT /rostering/1.0/courses/{id} PUT /rostering/1.0/units/{id} PUT /rostering/1.0/lessons/{id}

  2. Recognize TimeBack students in your app

    Every event you send has to reference the student by their TimeBack sourcedId. Partners get that ID by offering "Sign in with TimeBack" as an authentication option on their login screen. See Identity below for the full flow.

  3. Authenticate your backend to the Partner API

    All writes (events, content publishing) and all reads (roster, analytics) are backend-to-backend, authorized with an OAuth2 client-credentials token. Your partner bundle includes the client_id / client_secret and the token endpoint. This is separate from however your users log in; it's purely your server authenticating itself to ours.

    POST /auth/1.0/token

  4. Emit the Caliper events we expect, as they happen

    We've defined the event types we want and what each one means — see Events. Match the moments in your app (logged in, viewed content, answered a question, finished an assignment, earned XP) to those event types and send them. Each event references the student, the course, and the lesson.

    POST /events/1.0/

  5. Report XP on a GradeEvent when earned

    When your app decides the student has earned XP, include scoreType: "XP" and scoreGiven: N on the GradeEvent. TimeBack credits that XP against the student's enrollment and surfaces it in every downstream dashboard.

◆

Why we ask you to publish lessons — even if your content is dynamic

A lesson represents your app teaching a specific topic a student's performance can be audited against. It doesn't have to be a static piece of authored content — an AI tutor might publish one lesson per topic; an adaptive problem pool might publish one lesson per skill; a typing trainer might publish one lesson per exercise type. What matters is that every meaningful student action your app emits can be traced back to a named topic.

Lesson-level metrics are how Alpha dynamically assigns students work, fills gaps in their mastery, and accelerates students who've already mastered a topic instead of holding them back. Without lesson grain, none of that is possible — and students pay for it.

Lesson sourcedIds are stable forever. A content revision reuses the same ID; renaming or reordering is fine, changing the ID is not.

Identity: Sign in with TimeBack

Every Caliper event you send references the student by their TimeBack sourcedId. The only supported way for a partner app to obtain that ID is to offer "Sign in with TimeBack" as an authentication option on your app's login screen — the same way you might offer "Sign in with Google" or "Sign in with Microsoft." Your existing login methods stay in place alongside it; TimeBack-authed students simply carry a TimeBack identity in addition to whatever else you support.

The flow

  1. Student clicks "Sign in with TimeBack" on your login screen. Your app redirects them to TimeBack's hosted login (OIDC / OAuth2 authorization-code flow with PKCE).
  2. Student authenticates against TimeBack's identity provider using credentials they already have as an Alpha student.
  3. TimeBack redirects back to your app with an authorization code, which your app exchanges for an ID token.
  4. Your app reads the sourcedId claim from the ID token and associates it with the student's session in your system.
  5. Every Caliper event you emit for that session references the student by that sourcedId. No follow-up roster lookup is needed.
◎

Your server still needs its own credentials

SSO authenticates the student. Your server still needs to authenticate to the Partner API before calling any endpoint (events, analytics, roster reads). That's a separate OAuth2 client-credentials flow using the client_id / client_secret shipped in your partner bundle. Both mechanisms coexist: SSO gives you the student's sourcedId, client-credentials gets your server a token to call the API with.

See the "Authentication" section of getting-started.html in your partner bundle for the exact OIDC endpoints, authorize / token URLs, PKCE code examples, and claim format.

Events: what we want you to send

Partners frequently ask us "what events should I send?" We have strong opinions. Match the moment in your app to the event type below — don't invent your own event vocabulary.

Event typeSend when…Produces
SessionEvent The student logs into your app, logs out, or times out of inactivity. Session records and time-on-task data.
ViewEvent The student views a lesson, video, reading, or other passive content. Engagement facts (time spent on content).
AssignableEvent The student starts or completes an assignment, problem set, or self-directed activity. Engagement facts (assignment lifecycle).
AssessmentItemEvent The student answers an individual question or problem (correct or incorrect). Per-item gradebook records + facts for question-level analytics.
AssessmentEvent The student completes a whole assessment (quiz, test, exercise set). Gradebook result + fact for the overall assessment.
GradeEvent You've decided the student has earned XP or a grade for their work — the moment of awarding. XP credit + gradebook result. This is where scoreType: "XP" and scoreGiven go.
◎

Minimum viable event stream

If you only implement two event types to start, make them SessionEvent (so we know the student was in your app) and GradeEvent (so XP and grades flow). Everything else is additive — AssessmentItemEvent and AssessmentEvent unlock finer-grained gradebook and question-level analytics; ViewEvent and AssignableEvent enrich engagement data but aren't load-bearing for XP.

Every event references the student (actor.id), the course (extensions.course.id), and the lesson (extensions.lesson.id). Full field-by-field schemas are in the Scalar API reference.

Two optional add-ons

Some partners pick up one or both of these. They're additive to the core integration — you can ship without them and add later if a real need shows up.

Read-back Optional

GET the analytics, insights, XP, and gradebook results TimeBack has materialized from your events. Power partner-side dashboards, admin reports, or program-management tooling without building your own data pipeline.

  • GET /xp/1.0/users/{id}/entries
  • GET /analytics/1.0/activity
  • GET /insights/1.0/users/{id}
  • GET /gradebook/1.0/assessment-results

Resources Optional

Publish individual content items (a specific video, a QTI item, a slide deck) as named resources addressable independent of their parent lesson. Only needed if your product or your customers want to reference resources directly — most partners don't.

  • PUT /rostering/1.0/resources/{id}

Testing-only endpoints

The Partner API deliberately exposes more write endpoints than a production integration needs. This lets you self-serve your initial testing without waiting on Alpha to stand up users and classes for you. Once you're in production, these writes belong to Alpha — not to your app.

EndpointTestingProduction
PUT /rostering/1.0/users/{id} Scaffolding Don't use Alpha rosters students.
PUT /rostering/1.0/classes/{id} Scaffolding Don't use Alpha creates classes when assigning your app.
PUT /rostering/1.0/enrollments/{id} Scaffolding Don't use Alpha owns enrollment.
PUT /rostering/1.0/students/{id}/agents/{agentId} Scaffolding Don't use Alpha manages guardian links.
PUT /rostering/1.0/courses/{id} Yes Yes You own your courses.
PUT /rostering/1.0/units/{id}, /lessons/{id} Yes Yes You own your content structure.
PUT /rostering/1.0/resources/{id} Optional Optional Only for the Resources add-on.
POST /events/1.0/ Yes Yes Your main production write.

A healthy production footprint for most partners is: periodic course/unit/lesson publishing, a stream of Caliper events, and read-only calls for dashboards. That's it.

How to scope your integration

A short playbook for a PM sitting down to map out the footprint:

  1. Name your courses. A course is the top-level track of content a student enrolls in. Most apps split theirs by grade band, subject, or product line — the right number falls out naturally from how your content is organized.
  2. Decide your lesson grain. The topic level at which you want student performance audited. Too coarse and Alpha can't dynamically assign or accelerate; too fine and you're publishing unmanageable volume. Middle ground: one lesson per skill, topic, or discrete teachable concept.
  3. Map your in-app moments to the event types we expect. See Events — we've told you exactly which events to send for which kinds of moments. Decide the XP amount (if any) on each GradeEvent.
  4. Plan "Sign in with TimeBack" on your login screen. See Identity. Plan the UI change as part of your integration work — it's how you receive each student's sourcedId.
  5. Decide if you need Read-back. Skip if you don't need partner-side dashboards or reporting.
  6. Decide if you need Resources. Skip unless you need to reference individual content items directly.
  7. Don't plan production user/class/enrollment writes. Those are testing-only — Alpha owns them in production.
◎

A useful prompt to paste into your LLM of choice

"Here is a summary of the TimeBack Partner API [paste this document]. Here is what my app does [describe]. Help me: (1) pick course and lesson grain, (2) map in-app moments to the Caliper event types we should emit, (3) plan the "Sign in with TimeBack" integration on my existing login screen, (4) list the specific API calls I'll make in production vs. in testing, (5) decide whether I need the Read-back or Resources add-ons, (6) identify what I'll need to build on my side that I don't have today."

Where to go deeper

You want to…Go here
See every endpoint, field, and payloadThe Scalar API reference (linked from your partner bundle)
Run your first end-to-end testThe getting-started.html in your partner bundle — walks through auth, creating users, and sending events
Understand Caliper event processing"Processing requirements" section of Getting Started
Look up auth scopes"Authentication" section of Getting Started
Set up "Sign in with TimeBack" in your app"Authentication" section of Getting Started — covers the OAuth2 / OIDC flow and the SSO redirect URIs you registered during provisioning

Questions, gaps, or "this still doesn't answer X" — tell your partner contact. This doc grows with the real questions partners ask.