Overview

Timeback provides API clients for direct access to the supported services below in TypeScript and Python. Use these when you need fine-grained control over API interactions or want to build custom integrations.

Available Clients

Client	Description	Typescript	Python
OneRoster	Rostering, enrollments, grades	✓	✓
EduBridge	Analytics and resources	✓	✓
Caliper	Learning event tracking	✓	✓
QTI	Assessments and questions	✓	✓
PowerPath	Adaptive learning paths	✓	✓
CASE	Competencies and standards	✓	✓
CLR	Comprehensive Learner Records	✓	✓
MasteryTrack	Test inventory and assignments	✓	✓
Webhooks	Webhook management and filters	✓	✓

Installation

Install individual clients as needed:

npm install @timeback/oneroster
npm install @timeback/edubridge
npm install @timeback/caliper
npm install @timeback/qti
npm install @timeback/powerpath
npm install @timeback/case
npm install @timeback/clr
npm install @timeback/webhooks
npm install @timeback/masterytrack

pnpm add @timeback/oneroster
pnpm add @timeback/edubridge
pnpm add @timeback/caliper
pnpm add @timeback/qti
pnpm add @timeback/powerpath
pnpm add @timeback/case
pnpm add @timeback/clr
pnpm add @timeback/webhooks
pnpm add @timeback/masterytrack

yarn add @timeback/oneroster
yarn add @timeback/edubridge
yarn add @timeback/caliper
yarn add @timeback/qti
yarn add @timeback/powerpath
yarn add @timeback/case
yarn add @timeback/clr
yarn add @timeback/webhooks
yarn add @timeback/masterytrack

bun add @timeback/oneroster
bun add @timeback/edubridge
bun add @timeback/caliper
bun add @timeback/qti
bun add @timeback/powerpath
bun add @timeback/case
bun add @timeback/clr
bun add @timeback/webhooks
bun add @timeback/masterytrack

pip install timeback-oneroster
pip install timeback-edubridge
pip install timeback-caliper
pip install timeback-qti
pip install timeback-powerpath
pip install timeback-case
pip install timeback-clr
pip install timeback-webhooks
pip install timeback-masterytrack

uv add timeback-oneroster
uv add timeback-edubridge
uv add timeback-caliper
uv add timeback-qti
uv add timeback-powerpath
uv add timeback-case
uv add timeback-clr
uv add timeback-webhooks
uv add timeback-masterytrack

Or install the composed client (MasteryTrack remains separate; TypeScript also includes Reporting, which is not in the reviewed Python core):

npm install @timeback/core

pnpm add @timeback/core

yarn add @timeback/core

bun add @timeback/core

pip install timeback-core

uv add timeback-core

Authentication

Most clients use the OAuth2 client credentials flow. MasteryTrack uses its API key and registered email to obtain a JWT from its authorizer. The examples below show environment and explicit URL configuration. Some clients also accept an auth provider or transport; see their specific types.

Environment Mode (Recommended)

Connect to Timeback platforms with automatic URL resolution:

import { OneRosterClient } from '@timeback/oneroster'

const client = new OneRosterClient({
    env: 'staging', // or 'production'
    auth: {
        clientId: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
    },
})

import os
from timeback_oneroster import OneRosterClient

client = OneRosterClient(
    env="staging",  # or "production"
    client_id=os.environ["ONEROSTER_CLIENT_ID"],
    client_secret=os.environ["ONEROSTER_CLIENT_SECRET"],
)

Explicit Mode

Connect to custom OneRoster APIs:

const client = new OneRosterClient({
    baseUrl: 'https://api.example.com',
    auth: {
        clientId: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
        authUrl: 'https://auth.example.com/oauth2/token',
    },
})

client = OneRosterClient(
    base_url="https://api.example.com",
    auth_url="https://auth.example.com/oauth2/token",
    client_id=os.environ["ONEROSTER_CLIENT_ID"],
    client_secret=os.environ["ONEROSTER_CLIENT_SECRET"],
)

Tokens are automatically managed:

Fetched on first request
Cached for subsequent requests
OAuth tokens are refreshed as needed according to the provider’s expiry cache. MasteryTrack uses a separate fixed-duration token cache.

SDK Integration

With a fully configured SDK server, direct clients are available through timeback.api. The browser client does not expose server API credentials or the same direct API namespace.

Inside your server code

// `timeback` is your configured SDK server, including identity callbacks.
const { data: users } = await timeback.api.oneroster.users.list()
const enrollments = await timeback.api.edubridge.enrollments.list({ userId })

Inside your server code

# `timeback` is the configured server returned by create_server().
users = await timeback.api.oneroster.users.list()
enrollments = await timeback.api.edubridge.enrollments.list(user_id=user_id)

See server setup or FastAPI for complete configuration and Caliper for event payloads.

Common Patterns

Many resource clients provide these operations. This notation is a guide to common patterns, not a guarantee that every service exposes every method:

client.users.list({ limit?, offset?, where? })
client.users.get(id)
client.users.exists(id)
client.users.create({ ...fields })
client.users.update(id, { ...fields })
client.users.upsert(id, { ...fields })
client.users.delete(id)
client.users.stream()

await client.users.list(limit=..., offset=..., where=...)
await client.users.get(id)
await client.users.create(...)
await client.users.update(id, ...)
await client.users.delete(id)
async for user in client.users.stream():
    ...

Method	Returns	Description
`list()`	`PageResult`	List with pagination/filters
`get()`	`Resource`	Get by ID
`exists()`	`boolean`	Check whether the resource exists; transport depends on the client
`create()`	`CreateResponse`	Create new resource
`update()`	`Resource \| void`	Update existing resource (throws if missing)
`upsert()`	`Resource \| void`	Create or update resource
`delete()`	`void`	Delete resource
`stream()`	`AsyncIterable`	Stream all results efficiently

Return values for update() and upsert() are client-specific:

Read the resource-specific signature; return shapes vary by operation
Some APIs return no body on write, so the SDK returns void
In OneRoster specifically: rostering/resources return void, while gradebook/assessment return the updated entity

Environment Configuration

Configure clients via environment variables (when using environment mode, URLs are auto-resolved):

.env

# OneRoster
ONEROSTER_CLIENT_ID=your-client-id
ONEROSTER_CLIENT_SECRET=your-client-secret

# EduBridge
EDUBRIDGE_CLIENT_ID=your-client-id
EDUBRIDGE_CLIENT_SECRET=your-client-secret

# Caliper
CALIPER_CLIENT_ID=your-client-id
CALIPER_CLIENT_SECRET=your-client-secret

# QTI
QTI_CLIENT_ID=your-client-id
QTI_CLIENT_SECRET=your-client-secret

# CASE
CASE_CLIENT_ID=your-client-id
CASE_CLIENT_SECRET=your-client-secret

# CLR
CLR_CLIENT_ID=your-client-id
CLR_CLIENT_SECRET=your-client-secret

# MasteryTrack (uses API key + email, not OAuth)
MASTERYTRACK_API_KEY=your-api-key
MASTERYTRACK_EMAIL=your-registered-email

# Webhooks
WEBHOOKS_CLIENT_ID=your-client-id
WEBHOOKS_CLIENT_SECRET=your-client-secret

Client Guides

OneRoster

Rostering, enrollments, and gradebook

EduBridge

Analytics and resource management

Caliper

Learning analytics events

QTI

Assessments and questions

PowerPath

Adaptive learning paths

CASE

Competencies and standards

CLR

Comprehensive Learner Records

MasteryTrack

Test inventory and assignments

Webhooks

Webhook management and filters

Getting Started

CLI

SDK

Reference

Available Clients

Installation

Authentication

Environment Mode (Recommended)

Explicit Mode

SDK Integration

Common Patterns

Environment Configuration

Client Guides

OneRoster

EduBridge

Caliper

QTI

PowerPath

CASE

CLR

MasteryTrack

Webhooks

Getting Started

CLI

SDK

Reference

​Available Clients

​Installation

​Authentication

​Environment Mode (Recommended)

​Explicit Mode

​SDK Integration

​Common Patterns

​Environment Configuration

​Client Guides

OneRoster

EduBridge

Caliper

QTI

PowerPath

CASE

CLR

MasteryTrack

Webhooks

Available Clients

Installation

Authentication

Environment Mode (Recommended)

Explicit Mode

SDK Integration

Common Patterns

Environment Configuration

Client Guides