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"

This checks whether an email resolves to a Timeback account. It does not authenticate the caller or prove ownership of that email. Use an email from your authenticated session when gating access. Missing accounts return verified: false; ambiguous matches and lookup failures reject.

boolean

Whether the user exists in Timeback.

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.

string

Display name.

object

School the user belongs to.

Show properties

string

School ID.

string

School name.

number

Grade level.

object[]

Returned enrolled courses. A matching entry in timeback.config.json supplies the course code; unmatched courses fall back to their ID.

Show properties

string

Course ID.

string

Course code.

string

Course name.

object

Goals from the first returned enrollment whose metadata contains goals. This is not an aggregate across enrollments.

Show properties

number

Daily XP target.

number

Daily lesson target.

number

Daily active minutes target.

number

Daily accuracy target.

number

Daily mastered units target.

object

XP summed across the returned EduBridge activity facts for this user, without an app filter.

Show properties

number

XP earned during the current UTC day.

number

XP in the queried range from January 1, 2000 through the current UTC day.

Client-Side

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

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 profile = createTimebackProfile()
    const loaded = () => {
        const value = profile.state
        return value.status === "loaded" ? value.profile : undefined
    }

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

Show profile fields

string

Timeback user ID.

string

User’s email address.

string

Display name.

object

School the user belongs to.

Show properties

string

School ID.

string

School name.

number

Grade level.

object[]

Returned enrolled courses. A matching entry in timeback.config.json supplies the course code; unmatched courses fall back to their ID.

Show properties

string

Course ID.

string

Course code.

string

Course name.

object

Goals from the first returned enrollment whose metadata contains goals. This is not an aggregate across enrollments.

Show properties

number

Daily XP target.

number

Daily lesson target.

number

Daily active minutes target.

number

Daily accuracy target.

number

Daily mastered units target.

object

XP summed across the returned EduBridge activity facts for this user, without an app filter.

Show properties

number

XP earned during the current UTC day.

number

XP in the queried range from January 1, 2000 through the current UTC day.

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 requests share an in-flight request and a five-second cache per client instance. Verification has a separate 1.5-second cache.
fetchProfile() can reuse the fresh cache; the hook’s refresh() bypasses it.
The reviewed shared cache has no explicit sign-out invalidation function. Hook state resets when verification becomes unverified; do not treat cached profile presence as authorization.

The profile XP totals sum the user’s returned EduBridge facts across apps, not only this integration. Courses include returned enrollments; configuration supplies a course code when matched, rather than filtering the list. Goals come from the first returned enrollment with goals.

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

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