Overview

Timeback provides API clients for direct access to all services in both 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 all via the unified client:

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

All clients use OAuth 2.0 client credentials flow. There are two configuration modes:

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!,
	},
})

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
Refreshed when expired

SDK Integration

When using the full SDK, clients are available via timeback.api:

import { createTimeback } from '@timeback/sdk'

const timeback = await createTimeback({
	env: 'staging',
	api: {
		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
	},
	identity: {
		/* ... */
	},
})

const { data: users } = await timeback.api.oneroster.users.list()
const enrollments = await timeback.api.edubridge.enrollments.list({ userId })
await timeback.api.caliper.events.sendActivity(sensorUrl, activityData)

from timeback.server import create_server, TimebackConfig, ApiCredentials

timeback = create_server(TimebackConfig(
    env="staging",
    api=ApiCredentials(
        client_id=os.environ["TIMEBACK_API_CLIENT_ID"],
        client_secret=os.environ["TIMEBACK_API_CLIENT_SECRET"],
    ),
))

users = await timeback.api.oneroster.users.list()
enrollments = await timeback.api.edubridge.enrollments.list(user_id=user_id)
await timeback.api.caliper.events.send_activity(sensor_url, activity_data)

Common Patterns

All clients follow consistent CRUD patterns:

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 if resource exists (lightweight HEAD)
`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:

Most clients return the updated entity
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

​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