User Profile

Overview

The user profile contains an enriched view of the current user, including identity information, school, grade, enrolled courses, goals, and XP totals. You can access user data in several ways:

Server-side: verify users or fetch profiles directly from your backend
Client-side: use a framework hook with built-in state and caching

Server-Side

The timeback.user namespace provides programmatic methods that accept an email directly. Use them in your own API routes, server actions, webhooks, cron jobs, or any backend context.

Verify a user

Use timeback.user.verify(email) to check whether a Timeback user exists for a given email. This is a lightweight check — it does not fetch enrollments, analytics, or build an enriched profile.

const result = await timeback.user.verify('student@example.com')

if (result.verified) {
	console.log(result.timebackId) // "tb_abc123"
}

result = await timeback.user.verify("student@example.com")

if result.verified:
    print(result.timeback_id)  # "tb_abc123"

Useful for gating features (e.g., offering a free tier to Timeback users) without the cost of a full profile fetch.

verified

boolean

Whether the user exists in Timeback.

timebackId

string

The Timeback user ID. Only present when verified is true.

Get a user profile

Use timeback.user.getProfile(email) to get the full enriched profile — identity, enrollments, courses, goals, and XP. This is the programmatic equivalent of the /user/me HTTP handler.

const email = 'student@example.com'
const profile = await timeback.user.getProfile(email)

email = "student@example.com"
profile = await timeback.user.get_profile(email)

Throws a TimebackUserResolutionError if the user cannot be resolved. If you’re not sure whether a user exists, call verify() first.

Show profile fields

string

Timeback user ID.

string

User’s email address.

name

string

Display name.

school

object

School the user belongs to.

Show properties

string

School ID.

name

string

School name.

grade

number

Grade level.

courses

object[]

Enrolled courses matched against timeback.config.json.

Show properties

string

Course ID.

code

string

Course code.

name

string

Course name.

goals

object

Goals from the user’s enrollment metadata.

Show properties

dailyXp

number

Daily XP target.

dailyLessons

number

Daily lesson target.

dailyActiveMinutes

number

Daily active minutes target.

dailyAccuracy

number

Daily accuracy target.

dailyMasteredUnits

number

Daily mastered units target.

object

XP earned on this app. Calculated from Caliper events sent during activity tracking.

Show properties

today

number

XP earned during the current UTC day.

all

number

Total XP over all time.

Client-Side

On the client, use the framework-specific profile hook. The hook handles loading state, caching, and session-aware refetching — you never call timeback.user.fetch() directly from the browser.

React
Vue
Svelte
Solid

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

// Manual fetch
function ProfileButton() {
	const { state, canFetch, fetchProfile } = useTimebackProfile()

	if (state.status === 'loaded') {
		return <div>XP: {state.profile.xp.today}</div>
	}

	return (
		<button onClick={fetchProfile} disabled={!canFetch}>
			{state.status === 'loading' ? 'Loading...' : 'Load Profile'}
		</button>
	)
}

// Auto-fetch when verified
function AutoProfile() {
	const { state } = useTimebackProfile({ auto: true })

	if (state.status === 'loading') return <div>Loading...</div>
	if (state.status === 'loaded') return <div>XP: {state.profile.xp.today}</div>

	return null
}

<script setup>
import { useTimebackProfile } from '@timeback/sdk/vue'

const { state, canFetch, fetchProfile } = useTimebackProfile()
</script>

<template>
  <div v-if="state.status === 'loaded'">
    XP: {{ state.profile.xp.today }}
  </div>
  <button v-else @click="fetchProfile" :disabled="!canFetch">
    {{ state.status === 'loading' ? 'Loading...' : 'Load Profile' }}
  </button>
</template>

<script>
  import {
    timebackProfile,
    timebackProfileCanFetch,
    fetchTimebackProfile
  } from '@timeback/sdk/svelte'
</script>

<button onclick={fetchTimebackProfile} disabled={!$timebackProfileCanFetch}>
  {$timebackProfile.status === 'loading' ? 'Loading...' : 'Load Profile'}
</button>

{#if $timebackProfile.status === 'loaded'}
  <div>XP: {$timebackProfile.profile.xp.today}</div>
{/if}

import { createTimebackProfile } from '@timeback/sdk/solid'
import { Show } from 'solid-js'

function ProfileButton() {
	const { state, canFetch, fetchProfile } = createTimebackProfile()

	return (
		<Show
			when={state.status === 'loaded'}
			fallback={
				<button onClick={fetchProfile} disabled={!canFetch}>
					{state.status === 'loading' ? 'Loading...' : 'Load Profile'}
				</button>
			}
		>
			<div>XP: {state.profile.xp.today}</div>
		</Show>
	)
}

Show profile fields

string

Timeback user ID.

string

User’s email address.

name

string

Display name.

school

object

School the user belongs to.

Show properties

string

School ID.

name

string

School name.

grade

number

Grade level.

courses

object[]

Enrolled courses matched against timeback.config.json.

Show properties

string

Course ID.

code

string

Course code.

name

string

Course name.

goals

object

Goals from the user’s enrollment metadata.

Show properties

dailyXp

number

Daily XP target.

dailyLessons

number

Daily lesson target.

dailyActiveMinutes

number

Daily active minutes target.

dailyAccuracy

number

Daily accuracy target.

dailyMasteredUnits

number

Daily mastered units target.

object

XP earned on this app. Calculated from Caliper events sent during activity tracking.

Show properties

today

number

XP earned during the current UTC day.

all

number

Total XP over all time.

Hook State

The profile hook returns a state object with these statuses:

Status	Description
`idle`	Initial state, no fetch attempted
`loading`	Fetch in progress
`loaded`	Profile successfully loaded
`error`	Fetch failed

Caching

The client SDK caches profile data to minimize API calls:

Profile is fetched once per session
Manual refetch available via fetchProfile()
Cache is invalidated on sign-out

Next Steps

Custom Activities

Track activities to earn XP

Identity

Authentication setup

EduBridge Client

Advanced analytics queries

OneRoster Client

Query enrollments directly

Getting Started

CLI

SDK

Reference

Overview

Server-Side

Verify a user

Get a user profile

Client-Side

Hook State

Caching

Next Steps

Custom Activities

Identity

EduBridge Client

OneRoster Client

​Overview

​Server-Side

​Verify a user

​Get a user profile

​Client-Side

​Hook State

​Caching

​Next Steps

Custom Activities

Identity

EduBridge Client

OneRoster Client

Overview

Server-Side

Verify a user

Get a user profile

Client-Side

Hook State

Caching

Next Steps