App Lifecycle

Every App on the TimeBack Platform has a tier that controls what it can do against production. New Apps start in draft; once your integration is stable, you promote to active. This page describes what each tier permits, how promotion works, and how credentials behave across the transition.

Tiers at a Glance

Tier	Sandbox access	Production access	When
draft	Full sandbox-tier scopes	Read-only — currently lti.readonly scope only; broader scopes unlock on promotion	Default at registration
active	Full sandbox-tier scopes (unchanged)	Full active-tier scopes (expanded at promotion)	After promotion is approved

draft is the right place to build and test. You can integrate end-to-end against sandbox.platform.timeback.com while your prod-tier App sits in read-only mode, so no production traffic is at risk during development. When you're confident the integration is correct, request promotion.

What draft Permits in Production

• Schema discovery. Read OpenAPI specs and metadata via GET /applications/1.0/{appId} and related read endpoints on platform.timeback.com.
• Token issuance. Your prod-draft credentials issue valid access tokens, but their scope set is narrow — write operations against production are rejected.
• Sandbox-tier behavior on sandbox. Sandbox access is unaffected by the draft/active distinction; that's where active integration work happens. See Sandbox Environment.

What active Adds

After promotion, your production OAuth client's scope set expands from draft-tier to active-tier. Your existing access-token issuance flow keeps working unchanged — you just receive expanded scopes on subsequent tokens.

The exact set of active-tier scopes depends on what your App requested and what the platform approved. The base set typically includes write access to OneRoster rostering, Caliper event ingest, and any App-scoped data you write during normal operation.

Promotion Flow

Coming soon. The self-serve draft → active promotion flow (developer activation-request REST endpoint, platform-team CLI approval, audit-logged state transition) is in design. Once it ships, this section will document the request shape, the review criteria, and the approval timeline.

Until promotion is self-serve, contact TimeBack support to request promotion. Include your App ID, a brief description of how your App uses the platform in production, and any custom scopes you need.

Credential Continuity (Important)

Important: Your production OAuth client is stable across promotion. Promotion expands what your existing credentials can do; it does not issue new credentials.

• Same clientId.
• Same clientSecret.
• Same token-exchange flow.
• Expanded scopes on tokens issued after promotion.

You do not need to rotate credentials, re-deploy, or change anything in your App at approval time. The first token issued after promotion will carry the expanded scope set automatically.

The continuity rule is enforced at the platform level — the prod-side auth_client row is the same row throughout your App's lifetime, only its scope grants change.

Sandbox vs Production Credentials

Sandbox and production credentials are two independent secrets, issued from two independent OAuth provider pools. Promotion only affects the production-side credential's scopes; your sandbox credentials are untouched.

• Within prod: continuity (draft → active) — same clientId, same clientSecret, expanded scopes.
• Between sandbox and prod: no continuity — two separate clientId / clientSecret pairs you keep both of forever.

Store both pairs separately (different environment variables, different secrets-manager keys). A production deploy reads the prod pair; CI integration tests against sandbox read the sandbox pair.

Tier and Caliper Events

Caliper events sent from your App are tagged with your App URN at ingest. The platform validates that the edApp URN matches a registered App in the requesting environment (sandbox events checked against the sandbox env, production events checked against the production env). A draft-tier App can send Caliper events from sandbox; whether draft-tier Apps can send Caliper events directly against production is governed by your specific scope grants.

---

Related Docs

Level 0: Register Your App

Register your App in draft tier and receive credentials.

Sandbox Environment

The right place to exercise your integration end-to-end while your App is still in draft.

Authentication Guide

How the same clientId + clientSecret issue tokens with different scope sets before and after promotion.