Sandbox Environment

A dedicated playground for building and testing your TimeBack integration before pointing production traffic at it. The sandbox runs at sandbox.platform.timeback.com — same API shape as production, different host, separate credentials, isolated data.

What the Sandbox Is

The sandbox is a TimeBack-side environment provisioned specifically for external developer experimentation. Multiple Apps coexist in it (shared multi-tenant), each isolated from the others by per-App authorization grants. "Shared" describes the infrastructure, not your data: each Publisher gets a disjoint seeded tenant and your App's writes are never visible to another Publisher (see What's Seeded below). You can run integration tests, exercise error paths, and demo end-to-end flows without affecting any production cohort and without risking accidental writes against real student data.

The sandbox env is independent of TimeBack's internal platform.dev.timeback.com staging env. Staging carries TimeBack's pre-release-validation traffic for internal partner integrations; the sandbox is yours.

Prerequisites

• A registered App. See Level 0: Register Your App.
• Sandbox credentials. Sandbox uses a separate OAuth pool from production with its own clientId / clientSecret. There is no continuity between sandbox and production credentials; you keep both forever as two independent secrets.

Your registration response includes both prod-draft and sandbox clientId + clientSecret. Save both pairs to your secrets store — they're independent credentials issued from independent OAuth pools.

What's Seeded

On your first App registration, the platform automatically seeds a per-Publisher sandbox tenant — a stable set of fixture data scoped to your Publisher and invisible to other developers:

• 3 organizations
• 6 courses, 6 classes, 6 teachers
• 30 students, 36 enrollments

Every entity's URN is derived deterministically from (publisherId, kind, key), which guarantees three properties you can rely on in tests:

• Idempotent re-registration. Registering a second App under the same Publisher upserts against the existing tenant — no new entities, no collisions.
• Per-Publisher isolation. Different Publishers get disjoint sandbox tenants; your seeded students never appear in another developer's sandbox queries.
• Stable URNs across deploys. Hard-coding URN references in integration tests is safe.

Discover your tenant's actual URNs via the OneRoster API on sandbox.platform.timeback.com: GET /rostering/1.0/orgs, /students, /classes, etc. Responses are scoped to your Publisher's seeded data automatically.

What You Can Do

• Read OneRoster data. Query the canonical roster via GET /rostering/1.0/orgs, /students, /users, /classes against sandbox.platform.timeback.com.
• Send Caliper events. Post structured learning events from your App and verify they land.
• Write App-scoped state. Any data your App writes (assignments, scopes, metadata) is scoped to your App and invisible to other developers' Apps in the same sandbox env.

Coming soon. Caliper ingest will be auto-enabled for sandbox-tier Apps and a devplatform_list_events tool will surface a live event log so you can verify events landed. Today, Caliper requests against sandbox credentials may not succeed without an explicit scope grant; contact TimeBack support if you need Caliper enabled in advance of the auto-enable rollout.

Differences From Production

When your integration works against sandbox, it will work against production unmodified — only the host URL and the credential pair change.

Reset Semantics

Iterative testing often leaves App-scoped writes you'd like to clear without touching the canonical roster (which is platform-owned and shared with every other developer in the sandbox).

Coming soon. A sandbox-only reset verb will let you wipe your App's writes without touching the canonical roster. Until then, contact TimeBack support for App-scoped state cleanup.

The reset will be structurally impossible to invoke against production — the reset Lambda is declared only in the sandbox stack, so production's deployed infrastructure does not contain it.

Rate Limits and Error Semantics

Rate limits are applied per auth_client (per credential pair), matching production's protection model. Error envelopes match production's shape: structured error + nextAction fields where applicable, standard HTTP status codes. If you bake retry/backoff logic for production, the same logic works in sandbox.

Concrete per-App rate-limit numbers are configured at registration; if you hit limits during development, contact TimeBack support.

Pointing Your Code at Sandbox

Swap the host. Everything else stays the same.

- const BASE_URL = 'https://platform.timeback.com';
+ const BASE_URL = 'https://sandbox.platform.timeback.com';

- const CLIENT_ID = process.env.TIMEBACK_PROD_CLIENT_ID;
- const CLIENT_SECRET = process.env.TIMEBACK_PROD_CLIENT_SECRET;
+ const CLIENT_ID = process.env.TIMEBACK_SANDBOX_CLIENT_ID;
+ const CLIENT_SECRET = process.env.TIMEBACK_SANDBOX_CLIENT_SECRET;

Token exchange, request shape, response shape — all identical.

Related Docs

Level 0: Register Your App

Register your App and receive credentials before pointing them at the sandbox.

App Lifecycle

How draft and active tiers work, and how sandbox usage relates to the promotion flow.

Authentication Guide

Exchange your sandbox clientId + clientSecret for an access token.

Level 3: Caliper Events

Send learning events from your App; the sandbox is the right place to verify event shape before going live.