Examples - Timeback Docs (Beta)

Templates and example integrations help you move faster and avoid rework. Use these as starting points for your integration.

Starter Templates

Template	Framework	Description
`nextjs-app-router`	Next.js	App Router with SSO and activity tracking
`nuxt`	Nuxt 3	Server middleware with Vue composables
`svelte-kit`	SvelteKit	Hooks-based integration with stores
`solid-start`	SolidStart	Middleware with primitives
`tanstack-start`	TanStack Start	File-based routes with React
`express`	Express	Standalone API server
`express-auth0`	Express + Auth0	Custom auth mode with Auth0
`express-supabase`	Express + Supabase	Custom auth mode with Supabase
`bun-react`	Bun + React	Minimal SSO example
`bun-react-identity-only`	Bun + React	Identity-only mode (no activity tracking)

All templates are available in the examples directory.

bun-react

Source: examples/bun-react

SSO authentication and activity tracking with Bun server and React frontend. This example shows the SDK handlers (/api/timeback/*) plus a simple UI. For an example that also demonstrates the direct API escape hatch (timeback.api), see examples/bun-react-full.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun dev

Structure

File	Purpose
`src/index.ts`	Bun server + Timeback routes
`src/lib/timeback.ts`	SSO config + session management
`src/App.tsx`	SignInButton + activity demo
`src/frontend.tsx`	React entry point

Key Patterns

Native handler — Mount Timeback routes:

// index.ts
import { timebackHandler } from './lib/timeback'

if (url.pathname.startsWith('/api/timeback')) {
	return timebackHandler(request)
}

SignInButton — Pre-styled SSO button:

import { SignInButton } from '@timeback/sdk/react'

;<SignInButton />

Activity tracking — Track learning time:

import { useTimeback } from '@timeback/sdk/react'

const timeback = useTimeback()

const activity = timeback.activity.start({
  id: 'lesson_1',
  name: 'Fractions',
  course: { subject: 'FastMath', grade: 3 }, // must match timeback.config.json
})

<p>Time: {activity.elapsedMs}ms</p>

bun-react-full

Source: examples/bun-react-full

SSO authentication and activity tracking with Bun server and React frontend. This “full” variant also includes a small demo of direct API access via timeback.api (an escape hatch for calling Timeback services like OneRoster).

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun dev

Structure

File	Purpose
`src/index.ts`	Bun server + Timeback routes
`src/lib/timeback.ts`	SSO config + session management
`src/App.tsx`	SignInButton + activity demo
`src/frontend.tsx`	React entry point

Key Patterns

Native handler — Mount Timeback routes:

// index.ts
import { timebackHandler } from './lib/timeback'

if (url.pathname.startsWith('/api/timeback')) {
	return timebackHandler(request)
}

SignInButton — Pre-styled SSO button:

import { SignInButton } from '@timeback/sdk/react'

;<SignInButton />

Activity tracking — Track learning time:

import { useActivity } from '@timeback/sdk/react'

const activity = useActivity({
  id: 'lesson_1',
  name: 'Fractions',
  course: { subject: 'FastMath', grade: 3 } // must match a unique course in timeback.config.json
})

<p>Time: {activity.elapsedMs}ms</p>

bun-react-gradeless

Source: examples/bun-react-gradeless

SSO authentication and activity tracking for grade-less apps (e.g., CS platforms). This example demonstrates using courseCode instead of (subject, grade) for course identity.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun dev

Grade-less Course Configuration

Apps without grade levels use courseCode as the course identifier:

// timeback.config.json
{
	"$schema": "https://timeback.dev/schema.json",
	"name": "CodeQuest",
	"courses": [
		{
			"subject": "Other",
			"courseCode": "INTRO-CS-101",
			"ids": { "staging": "...", "production": "..." }
		},
		{
			"subject": "Other",
			"courseCode": "DATA-STRUCTURES-201",
			"ids": { "staging": "...", "production": "..." }
		}
	]
}

Activity Tracking with courseCode

When evaluating examples, it’s often useful to preview what would be sent without actually sending Caliper events. This example uses:

normal activity.end(...) (production-like)
a server-side hook (beforeActivitySend) to optionally skip sending and log what would be sent

Demo toggle

In .env:

# 0 = preview (log would-send events, do not send)
# 1 = send for real
TIMEBACK_DEMO_SEND_ACTIVITY=0

Compare this to grade-based apps (see examples/bun-react):

// Grade-based
course: { subject: 'Math', grade: 3 }

Structure

File	Purpose
`src/index.ts`	Bun server + Timeback routes
`src/lib/timeback.ts`	SSO config + session management
`src/App.tsx`	SignInButton + activity demo
`timeback.config.json`	Grade-less course configuration

bun-react-identity-only

Source: examples/bun-react-identity-only

SSO authentication with Bun server and React frontend — no activity tracking. This example demonstrates createTimebackIdentity() for apps that only need Timeback SSO without the full SDK.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun dev

Structure

File	Purpose
`src/index.ts`	Bun server + Timeback routes
`src/lib/timeback.ts`	SSO config + session management
`src/App.tsx`	SignInButton + session display
`src/frontend.tsx`	React entry point

Key Differences from Full SDK

Uses createTimebackIdentity() instead of createTimeback()
No api credentials required
No timeback.config.json required
Only identity routes are available (no activity tracking)

Key Patterns

Identity-only server — No API credentials needed:

// lib/timeback.ts
import { createTimebackIdentity } from '@timeback/sdk/edge'

export const timeback = createTimebackIdentity({
	env: 'staging',
	identity: {
		mode: 'sso',
		clientId: process.env.TIMEBACK_SSO_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_SSO_CLIENT_SECRET!,
		onCallbackSuccess: ({ user, redirect }) => {
			setSession(user)
			return redirect('/')
		},
		getUser: () => getSession(),
	},
})

SignInButton — Pre-styled SSO button:

import { SignInButton } from '@timeback/sdk/react'

;<SignInButton />

express

Source: examples/express

Minimal Express.js backend demonstrating the Timeback SDK’s Express adapter.

Quick Start

bun install
bun dev

Verify Routes

Run the verification script to test all routes:

bun run verify

This starts the server, tests all endpoints, and reports results.

Routes

Method	Path	Description
GET	`/health`	Health check
GET	`/api/timeback/identity/signin`	Initiate SSO sign-in
GET	`/api/timeback/identity/callback`	SSO callback handler
GET	`/api/timeback/identity/signout`	Sign out
POST	`/api/timeback/activity`	Submit activity events

Testing

# Health check
curl http://localhost:3000/health

# Submit activity (requires authentication)
curl -X POST http://localhost:3000/api/timeback/activity \
  -H "Content-Type: application/json" \
  -d '{
    "id": "lesson-123",
    "name": "Introduction to Fractions",
    "course": { "subject": "FastMath", "grade": 3 },
    "startedAt": "2026-01-16T10:00:00Z",
    "endedAt": "2026-01-16T10:05:00Z",
    "elapsedMs": 300000,
    "pausedMs": 0,
    "metrics": { "totalQuestions": 10, "correctQuestions": 8 }
  }'

Integration Options

The SDK provides two ways to integrate with Express:

Option 1: Middleware (recommended)

import { toExpressMiddleware } from '@timeback/sdk/express'

app.use('/api/timeback', toExpressMiddleware(timeback))

Option 2: Router mounting

import { mountExpressRoutes } from '@timeback/sdk/express'

const router = express.Router()
mountExpressRoutes(timeback, router)
app.use('/api/timeback', router)

express-auth0

Source: examples/express-auth0

Demonstrates using the Timeback SDK with Auth0 as a custom identity provider. This example uses Auth0’s email/password authentication (Resource Owner Password Grant) with the official auth0 Node.js SDK.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (React)                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐  │
│  │ Login Form  │───▶│ POST /auth  │───▶│ Session Cookie Set  │  │
│  │ email/pass  │    │   /login    │    │ User State Updated  │  │
│  └─────────────┘    └─────────────┘    └─────────────────────┘  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              TimebackProvider + useTimeback             │    │
│  │  • Activity tracking      • Profile fetching            │    │
│  │  • Requests include session cookie automatically        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Backend (Express)                          │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │ POST /auth/login│───▶│ Auth0 SDK (passwordGrant)           │ │
│  │                 │    │ Validates credentials with Auth0    │ │
│  │                 │◀───│ Returns user info + tokens          │ │
│  │                 │    └─────────────────────────────────────┘ │
│  │ Creates session │                                            │
│  │ cookie (JWT)    │                                            │
│  └─────────────────┘                                            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Timeback SDK                         │    │
│  │  identity.mode: 'custom'                                │    │
│  │  getEmail: parses session cookie → returns email        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Auth0 Setup

Create an Auth0 Application
- Go to Auth0 Dashboard → Applications → Create Application
- Choose “Regular Web Application”
- Note your Domain, Client ID, and Client Secret
Enable Password Grant
- In your application settings, go to Advanced Settings → Grant Types
- Enable Password grant type
Create a Database Connection (if you don’t have one)
- Go to Authentication → Database → Create Connection
- Enable it for your application
Create Test Users
- Go to User Management → Users → Create User
- Create users with email/password

Quick Start

# Install dependencies
just install

# Copy environment template
just setup

# Edit backend/.env with your Auth0 credentials
# Then start development servers
just dev

Environment Variables

Create backend/.env from backend/.env.example:

# Auth0 (from your Auth0 Dashboard)
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

# Session secret (generate with: openssl rand -base64 32)
SESSION_SECRET=your-random-secret

# Timeback API (from Timeback Dashboard)
TIMEBACK_API_CLIENT_ID=your-timeback-client-id
TIMEBACK_API_CLIENT_SECRET=your-timeback-client-secret

How It Works

User submits email/password → Backend calls Auth0’s password grant → Auth0 validates → Returns user info → Backend creates signed JWT session cookie.

2. Session Management

The session cookie contains { sub, email, name } signed with HS256. It’s httpOnly, secure in production, and lasts 7 days.

3. Timeback Integration

// backend/src/lib/timeback.ts
export const timeback = await createTimeback({
	identity: {
		mode: 'custom',
		getEmail: async req => {
			const session = await getSessionFromCookieHeader(req.headers.get('cookie'))
			return session?.email
		},
	},
	// ...
})

The SDK calls getEmail(req) on each request. We parse the cookie header, verify the JWT, and return the user’s email. The SDK then resolves the Timeback user by email.

4. Frontend Activity Tracking

const timeback = useTimeback()

// Start tracking
const activity = timeback.activity.start({ id: 'lesson_1', name: 'Intro to Fractions' })

// End with results
await activity.end({ correctQuestions: 8, totalQuestions: 10 })

Project Structure

express-auth0/
├── backend/
│   ├── src/
│   │   ├── index.ts           # Express server & routes
│   │   └── lib/
│   │       ├── auth0.ts       # Auth0 SDK wrapper
│   │       ├── session.ts     # JWT session cookie helpers
│   │       └── timeback.ts    # Timeback SDK instance
│   ├── .env.example
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.tsx            # Main app with login form
│   │   ├── main.tsx           # Entry point with TimebackProvider
│   │   └── components/
│   └── package.json
├── justfile
└── README.md

API Routes

Method	Route	Description
GET	`/health`	Health check
POST	`/auth/login`	Login with email/password
POST	`/auth/logout`	Clear session cookie
GET	`/api/session`	Get current user
GET	`/api/timeback/user/me`	Timeback user profile
POST	`/api/timeback/activity`	Submit activity events

Troubleshooting

”Invalid email or password”

Verify the user exists in Auth0 (User Management → Users)
Check that the Password grant type is enabled
Ensure the database connection is enabled for your app

”Auth0 is not configured”

Check AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET in .env
Domain should be just your-tenant.auth0.com (no https://)

Session not persisting

Check browser dev tools → Application → Cookies
In development, cookies work on localhost
The Vite proxy ensures same-origin for cookie handling

CORS errors

The Vite dev server proxies /auth and /api to the backend
No CORS configuration needed in development

express-auth0-launch-gate

Source: examples/express-auth0-launch-gate

Activity tracking demo using Auth0 Universal Login (SPA + PKCE) in the frontend and Bearer-token auth in the backend, with a launch-gated entry URL (/timeback/signin).

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Frontend (React + Auth0 React SDK + @timeback/sdk)          │
│  - Auth0 Universal Login (PKCE)                              │
│  - Activity tracking with useTimeback()                     │
│  - Profile viewer                                           │
└─────────────────────────────────────────────────────────────┘
                              │
                  GET  /api/user/me    (Bearer)
                  POST /api/timeback/activity (Bearer)
                  GET  /api/timeback/user/me  (Bearer)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Backend (Express + Timeback SDK)                            │
│  - Validates Bearer JWTs via Auth0 JWKS                      │
│  - Custom identity mode (SDK resolves user by email claim)   │
│  - Activity tracking via Caliper                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Auth0                       │  Timeback API                │
│  - User authentication       │  - User resolution by email  │
│  - Password management       │  - Activity ingestion        │
└─────────────────────────────────────────────────────────────┘

How It Works

Auth0 handles authentication - Frontend uses Auth0 Universal Login (Authorization Code + PKCE)
Frontend calls backend with Bearer token - API requests include Authorization: Bearer {'<'}access_token{'>'}
Backend validates token - using Auth0 JWKS + issuer + audience
SDK uses custom identity mode - The getEmail callback reads email from the request
SDK resolves Timeback user - When submitting activity, SDK looks up the Timeback user by email

This pattern is ideal when:

You have an existing Auth0 SPA
Your backend is a resource server (Bearer JWT auth)
You want a dedicated Timeback launch URL (/timeback/signin) without a separate “Sign in with Timeback” button

Quick Start

1. Auth0 Setup

Create an API in Auth0 (Applications → APIs) and copy its Identifier (this is the audience)
Create a Single Page Application in Auth0 (Applications → Applications)
In the SPA settings, set:
- Allowed Callback URLs: http://localhost:5173
- Allowed Logout URLs: http://localhost:5173
- Allowed Web Origins: http://localhost:5173
Ensure the Database connection is enabled for the SPA (email/password hosted by Auth0)

2. Environment Setup

cd examples/express-auth0-launch-gate
cp .env.example .env

Edit .env with your credentials.

3. Install and Run

just install
just dev

Open http://localhost:5173

Launch-gated URL

Visit http://localhost:5173/timeback/signin to simulate the Timeback launch URL.

Commands

Command	Description
`just install`	Install backend + frontend
`just dev`	Start backend + frontend
`just dev-backend`	Start backend only
`just dev-frontend`	Start frontend only
`just setup`	Copy `.env.example` → `.env`

API Endpoints

Auth Endpoints

This example uses Auth0 Universal Login (SPA + PKCE), so there are no backend /auth/* routes. The backend behaves like a typical resource server: it only validates Authorization: Bearer {'<'}access_token{'>'}.

Timeback SDK Endpoints

Endpoint	Method	Description
`/api/timeback/activity`	POST	Submit activity to Caliper
`/api/timeback/user/me`	GET	Get Timeback user profile
`/api/timeback/user/verify`	GET	Verify Timeback user status

Session Endpoints

Endpoint	Method	Description
`/api/health`	GET	Health check
`/api/user/me`	GET	Auth0 user

Project Structure

express-auth0-launch-gate/
├── backend/
│   ├── src/
│   │   ├── index.ts           # Express server & routes
│   │   └── lib/
│   │       ├── auth.ts        # Bearer auth middleware
│   │       └── timeback.ts    # Timeback SDK instance
│   └── package.json
├── frontend/
│   └── src/
│       ├── App.tsx            # React app (Auth0 + launch gate)
│       └── main.tsx           # Auth0Provider + TimebackProvider
├── .env.example
├── justfile
└── README.md

express-supabase

Source: examples/express-supabase

Demonstrates using the Timeback SDK with Supabase as a custom identity provider.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (React)                        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Login/Signup Form → POST /auth/login or /auth/signup     │  │
│  │  Activity Tracking → SDK React hooks                      │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Backend (Express)                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  /auth/login    → Supabase signInWithPassword             │  │
│  │  /auth/signup   → Supabase signUp                         │  │
│  │  /auth/logout   → Clear session                           │  │
│  │  /api/session   → Return session user                     │  │
│  │  /api/timeback  → Timeback SDK routes                     │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Session: iron-session (encrypted cookie)                       │
│                                                                 │
│  Timeback SDK:                                                  │
│    identity: { mode: 'custom', getEmail: req => ... }           │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌──────────────────────┐         ┌──────────────────────┐
│      Supabase        │         │    Timeback API      │
│  (Authentication)    │         │  (Activity Events)   │
└──────────────────────┘         └──────────────────────┘

Setup

1. Install dependencies

just install

2. Configure environment

just setup

Edit backend/.env with your credentials:

Supabase: Get URL and Publishable key from Supabase Dashboard > Settings > API
Timeback: Get from Timeback Dashboard

3. Create a Supabase user

In your Supabase Dashboard:

Go to Authentication > Users
Click “Add user” > “Create new user”
Enter email and password

4. Start development servers

just dev

Frontend: http://localhost:5173
Backend: http://localhost:3001

Timeback Integration

The SDK is configured with custom identity mode, reading the user’s email from the session cookie:

// backend/src/lib/timeback.ts
export const timeback = await createTimeback({
	env: 'staging',
	identity: {
		mode: 'custom',
		getEmail: req => getEmailFromCookieHeader(req.headers.get('cookie')),
	},
	api: {
		clientId: process.env.TIMEBACK_API_CLIENT_ID,
		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET,
	},
})

Available Commands

Command	Description
`just install`	Install all dependencies
`just setup`	Create `.env` from template
`just dev`	Start both servers
`just dev-backend`	Start backend only
`just dev-frontend`	Start frontend only

nextjs-app-router

Source: examples/nextjs-app-router

SSO authentication and activity tracking with Next.js App Router.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun run dev

Structure

File	Purpose
`src/app/api/timeback/[...timeback]/`	Timeback request handler
`src/app/api/auth/sso/callback/timeback/`	Custom OAuth callback
`src/lib/timeback.ts`	SSO config + session management
`src/app/page.tsx`	SignInButton + activity demo

Key Patterns

API routes — Handle auth routes via toNextjsHandler:

// api/timeback/[...timeback]/route.ts
import { toNextjsHandler } from '@timeback/sdk/nextjs'

import { timeback } from '@/lib/timeback'

export const { GET, POST } = toNextjsHandler(timeback)

SignInButton — Pre-styled SSO button:

import { SignInButton } from '@timeback/sdk/react'

;<SignInButton />

Activity tracking — Track learning time:

import { useTimeback } from '@timeback/sdk/react'

function MyComponent() {
	const timeback = useTimeback()

	useEffect(() => {
		const activity = timeback?.activity.start({
			id: 'lesson-1',
			name: 'Fractions',
			courseCode: 'MATH-101',
		})

		return () => activity?.end({ xpEarned: 100 })
	}, [timeback])
}

nuxt

Source: examples/nuxt

Look at the Nuxt documentation to learn more.

Setup

Make sure to install dependencies:

# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install

Development Server

Start the development server on http://localhost:3000:

# npm
npm run dev

# pnpm
pnpm dev

# yarn
yarn dev

# bun
bun run dev

Production

Build the application for production:

# npm
npm run build

# pnpm
pnpm build

# yarn
yarn build

# bun
bun run build

Locally preview production build:

# npm
npm run preview

# pnpm
pnpm preview

# yarn
yarn preview

# bun
bun run preview

Check out the deployment documentation for more information.

solid-start

Source: examples/solid-start

SolidStart app with Timeback SSO authentication and activity tracking.

Quick Start

cp .env.example .env
# Add your Cognito credentials to .env
bun install
bun dev

File Structure

File	Purpose
`src/lib/timeback.ts`	SDK server instance with SSO config
`src/routes/api/timeback/[...path].ts`	Catch-all API route for SDK
`src/routes/api/auth/sso/callback/timeback.ts`	Custom OAuth callback
`src/routes/api/session.ts`	Session endpoint
`src/routes/api/signout.ts`	Sign out endpoint
`src/routes/index.tsx`	Main page with auth UI

Key Patterns

Server SDK → toSolidStartHandler(timeback) in API routes Client → SignInButton, Activity from timeback/solid Session → Server-side store, fetched via /api/session

svelte-kit

Source: examples/svelte-kit

SSO authentication and activity tracking with SvelteKit.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun run dev

Structure

File	Purpose
`src/hooks.server.ts`	Timeback request handler
`src/lib/timeback.ts`	SSO config + session management
`src/routes/+page.server.ts`	Pass session to page
`src/routes/+page.svelte`	SignInButton + activity demo

Key Patterns

Server hooks — Handle auth routes via svelteKitHandler:

// hooks.server.ts
export const handle = ({ event, resolve }) =>
	svelteKitHandler({ timeback, event, resolve, building })

SignInButton — Pre-styled SSO button:

<script>
	import SignInButton from '@timeback/sdk/svelte/SignInButton.svelte'
</script>

<SignInButton />

Activity tracking — Track learning time:

<script>
	import { timeback } from '@timeback/sdk/svelte'
	import { onMount } from 'svelte'

	let activity = $state(undefined)

	onMount(() => {
		activity = $timeback?.activity.start({ id: 'lesson_1', name: 'Fractions', courseCode: 'MATH-101' })
	})
</script>

<button onclick={() => activity?.end({ xpEarned: 100 })}>Submit</button>

tanstack-start

Source: examples/tanstack-start

SSO authentication and activity tracking with TanStack Start.

Quick Start

cp .env.example .env
# Add your TIMEBACK_SSO_CLIENT_ID and TIMEBACK_SSO_CLIENT_SECRET
bun install
bun dev

File Structure

File	Purpose
`src/lib/timeback.ts`	Server SDK configuration
`src/routes/api/timeback/$.ts`	Timeback API routes
`src/routes/api/auth/sso/callback/timeback.ts`	Custom OAuth callback
`src/routes/api/session.ts`	Session endpoint
`src/routes/api/signout.ts`	Sign out endpoint
`src/routes/index.tsx`	Main page with SSO demo
`timeback.config.json`	Course/app configuration

Key Patterns

Server config — Configure SSO in src/lib/timeback.ts:

export const timeback = await createTimeback({
	env: 'staging',
	identity: {
		mode: 'sso',
		clientId: process.env.TIMEBACK_SSO_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_SSO_CLIENT_SECRET!,
		redirectUri: 'http://localhost:5174/api/auth/sso/callback/timeback',
		onCallbackSuccess: ({ user, redirect }) => {
			setSession({ id: user.id, email: user.email })
			return redirect('/')
		},
		getUser: () => getSession(),
	},
})

API routes — Mount Timeback handlers:

// src/routes/api/timeback/$.ts
import { toTanStackStartHandler } from '@timeback/sdk/tanstack-start'

export const Route = createFileRoute('/api/timeback/$')({
	server: { handlers: toTanStackStartHandler(timeback) },
})

Client — Use the React adapter:

import { SignInButton, TimebackProvider, useTimeback } from '@timeback/sdk/react'

function App() {
	return (
		<TimebackProvider>
			<SignInButton />
		</TimebackProvider>
	)
}

Next Steps

Quickstart

Follow the CLI-based quickstart

SDK Overview

Learn about SDK features

Configuration

Full config reference

Developer Program

Apply for access

Getting Started

CLI

SDK

API Clients

Reference

​Starter Templates

​bun-react

​Quick Start

​Structure

​Key Patterns

​bun-react-full

​Quick Start

​Structure

​Key Patterns

​bun-react-gradeless

​Quick Start

​Grade-less Course Configuration

​Activity Tracking with courseCode

​Demo toggle

​Structure

​bun-react-identity-only

​Quick Start

​Structure

​Key Differences from Full SDK

​Key Patterns

​express

​Quick Start

​Verify Routes

​Routes

​Testing

​Integration Options

​Option 1: Middleware (recommended)

​Option 2: Router mounting

​express-auth0

​Architecture

​Auth0 Setup

​Quick Start

​Environment Variables

​How It Works

​1. User Login

​2. Session Management

​3. Timeback Integration

​4. Frontend Activity Tracking

​Project Structure

​API Routes

​Troubleshooting

​”Invalid email or password”

​”Auth0 is not configured”

​Session not persisting

​CORS errors

​express-auth0-launch-gate

​Architecture

​How It Works

​Quick Start

​1. Auth0 Setup

​2. Environment Setup

​3. Install and Run

​Launch-gated URL

​Commands

​API Endpoints

​Auth Endpoints

​Timeback SDK Endpoints

​Session Endpoints

​Project Structure

​express-supabase

​Architecture

​Setup

​1. Install dependencies

​2. Configure environment

​3. Create a Supabase user

​4. Start development servers

​Timeback Integration

​Available Commands

​nextjs-app-router

​Quick Start

​Structure

​Key Patterns

​nuxt

​Setup

​Development Server

Starter Templates

bun-react

Quick Start

Structure

Key Patterns

bun-react-full

Quick Start

Structure

Key Patterns

bun-react-gradeless

Quick Start

Grade-less Course Configuration

Activity Tracking with courseCode

Demo toggle

Structure

bun-react-identity-only

Quick Start

Structure

Key Differences from Full SDK

Key Patterns

express

Quick Start

Verify Routes

Routes

Testing

Integration Options

Option 1: Middleware (recommended)

Option 2: Router mounting

express-auth0

Architecture

Auth0 Setup

Quick Start

Environment Variables

How It Works

1. User Login

2. Session Management

3. Timeback Integration

4. Frontend Activity Tracking

Project Structure

API Routes

Troubleshooting

”Invalid email or password”

”Auth0 is not configured”

Session not persisting

CORS errors

express-auth0-launch-gate

Architecture

How It Works

Quick Start

1. Auth0 Setup

2. Environment Setup

3. Install and Run

Launch-gated URL

Commands

API Endpoints

Auth Endpoints

Timeback SDK Endpoints

Session Endpoints

Project Structure

express-supabase

Architecture

Setup

1. Install dependencies

2. Configure environment

3. Create a Supabase user

4. Start development servers

Timeback Integration

Available Commands

nextjs-app-router

Quick Start

Structure

Key Patterns

nuxt

Setup

Development Server

Production

solid-start

Quick Start

File Structure

Key Patterns