Level 0: Register Your App

Get your app listed in TimeBack's catalog so students can discover and launch it. Registration is self-serve: sign in with Google, call one tool or REST endpoint, and walk away with credentials in the same response. No email round-trip, no business-day waits.

What Registration Provides

Registering your app makes it discoverable in TimeBack's app catalog. Once registered, students can launch your app from TimeBack App, which automatically tracks session time, detects waste time, and provides coaching insights, without any implementation required from you.

Registration also provisions everything you need to start integrating:

• An App ID (UUID) plus its canonical App URN (urn:uuid:{App ID}) for use in Caliper events (the edApp field)
• OAuth client credentials (clientId + clientSecret) for the client-credentials flow against platform.timeback.com
• A draft-tier scope set so you can immediately exercise the read-only endpoints while you build

Prerequisites

• A Google account. Registration uses Google SSO; no separate TimeBack account exists.

Two Ways to Register

Both paths call the same backend; pick whichever fits your workflow.

Step 1: Sign In

MCP path (you build with Cursor / Claude Desktop / Claude Code / any MCP-capable agent):

Add https://platform.timeback.com/mcps/developer-platform as an MCP server in your client. The URL is an MCP server endpoint (not a browser URL) — it accepts MCP protocol calls and initiates Google SSO when your client first connects. The SSO popup your client opens is where the "sign in with Google" step actually happens.

For Cursor, in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "timeback-developer-platform": {
      "url": "https://platform.timeback.com/mcps/developer-platform"
    }
  }
}

For Claude Code: claude mcp add --transport http timeback-developer-platform https://platform.timeback.com/mcps/developer-platform.

On first call, your client opens a Google SSO popup. Sign in with the Google account you want associated with your App registrations — TimeBack uses your verified email to identify you and link subsequent registrations to your developer profile. If your email is already attached to a Publisher (your company or organization on the platform), the platform auto-resolves it.

REST path (curl, Postman, your backend):

You need a Cognito JWT to authenticate the POST /applications/1.0/drafts call. Today, the only documented way to obtain one is to complete the MCP-path Google SSO flow above and copy the access token your MCP client receives — the JWT is then valid as a Bearer token on the REST endpoint. A standalone OAuth Authorization Code flow for the REST path is on the roadmap.

Step 2: Register Your App

Provide three required fields (name, description, launchUrl) plus optional fields like applicationType. If you belong to more than one Publisher, pass publisherId; otherwise omit it.

REST example:

curl -X POST https://platform.timeback.com/applications/1.0/drafts \
  -H "Authorization: Bearer <YOUR_SSO_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TrashCat",
    "description": "An endless runner game that builds multiplication fact fluency through rapid-fire math drills.",
    "launchUrl": "https://trashcat.learnwith.ai/lti/launch"
  }'

MCP example (Cursor / Claude):

Call devplatform_register_app_as_draft with:
  name: "TrashCat"
  description: "An endless runner game that builds multiplication fact fluency through rapid-fire math drills."
  launchUrl: "https://trashcat.learnwith.ai/lti/launch"

Step 3: Save Your Credentials

The response carries everything you need to start integrating:

{
  "appUrn": "urn:uuid:53f0d94d-786d-409a-b5eb-7a6c1db8957b",
  "applicationId": "53f0d94d-786d-409a-b5eb-7a6c1db8957b",
  "publisherId": "11111111-2222-3333-4444-555555555555",
  "productionCredentials": {
    "clientId": "1a2b3c4d5e6f7g8h9i0j",
    "clientSecret": "supersecret-only-shown-once",
    "tokenUrl": "<value-from-registration-response>",
    "scopes": ["<scope-1>", "<scope-2>", "..."]
  },
  "sandboxCredentials": {
    "clientId": "0z9y8x7w6v5u4t3s2r1q",
    "clientSecret": "sandbox-secret-only-shown-once",
    "tokenUrl": "<value-from-registration-response>",
    "scopes": ["<scope-1>", "<scope-2>", "..."]
  },
  "sandboxStatus": "provisioned"
}

sandboxStatus is provisioned when both credential sets are returned. If the sandbox fan-out is still in flight, sandboxStatus is pending and sandboxCredentials is null until the platform backfills it.

Important: The clientSecret is returned exactly once. Capture it from this response and store it securely (a secrets manager, an environment variable, your CI vault). It cannot be retrieved again through the API; if you lose it, contact TimeBack support to rotate.

The response also includes a sandboxCredentials object with a separate clientId + clientSecret issued from the sandbox-side OAuth pool — save both pairs. See Sandbox Environment for what the sandbox provides.

Required Fields

Optional Fields

You can include these on registration to populate the catalog richly from day one, or add them later via PUT /applications/1.0/{sourcedApplicationId} (or the manage_app MCP tool on the platform MCP at platform.timeback.com/mcp).

Logo format: Must be PNG or JPG. SVG and WebP are not supported.

LTI: If you implement LTI 1.3 for seamless authentication, set the LTI fields at registration (in the optional fields above) or amend them later via PUT /applications/1.0/{sourcedApplicationId} once your launch endpoint is ready. See Level 2: LTI Launch for the field list and endpoint shape.

After Registration

Your draft App is now live in the catalog with draft-tier scopes. From here you can:

• Read the canonical roster in the sandbox env to test against realistic data — see Sandbox Environment.
• Send Caliper events from your App once Caliper scope is granted — see Level 3: Caliper Events.
• Manage students programmatically via the roster API — see Level 1: Student Onboarding.
• Implement LTI launch for seamless authentication — see Level 2: LTI Launch.
• Register webhook subscriptions to receive real-time event notifications — see Webhooks.
• Understand the draft → active lifecycle and when to request promotion — see App Lifecycle.

Next Steps

Start integrating against sandbox. The fastest path from registration to a working integration is to point your code at sandbox.platform.timeback.com with the sandbox credentials, exercise the roster and Caliper endpoints, and only switch to production once your behavior is stable. See Sandbox Environment.

Publish to TimeBack Store and earn revenue. Once your draft → active promotion is approved, list your app on store.timeback.com so parents can purchase access for their kids. See Store → Introduction for what the Store provides and how to publish.

Related Docs

Sandbox Environment

Build and test against a shared sandbox env with a canonical roster, isolated from prod.

App Lifecycle

How draft and active tiers work, and how to promote your App when you're ready for production traffic.

Authentication Guide

Exchange your clientId + clientSecret for an access token and call TimeBack APIs.

Level 1: Student Onboarding

Programmatically create and manage students, users, and agent relationships in TimeBack's roster.

Level 2: LTI Launch

Implement LTI 1.3 to enable seamless student authentication and eliminate login friction.

Level 3: Caliper Events

Send structured learning events to unlock coaching insights and unified progress analytics.

Webhooks

Receive real-time push notifications when platform events occur, instead of polling APIs.