Apps, environments & identity

Understand organizations, Apps, customers and credential boundaries.

SDK 0.0.1Updated Oct 14, 2026

A scoped identity

An organization contains product Apps. Every tenant-owned object belongs to an App and, where applicable, an environment.
Sandbox and Live hold separate customers, catalog data, surfaces and events. A credential is permanently bound to its App and environment.
Console members and SDK customers are separate identities. Email does not merge customer records.

X-Groove-Project and X-Groove-Environment validate a credential’s scope. They do not grant access or switch Apps.

Sessions and sign-out

Tokens stay in SDK memory. Refresh an expired token through your own authenticated backend; the SDK does not refresh automatically.
On sign-out or identity change, destroy active surfaces and call disconnectSession to abort the host session fetch as well as resetting the client. Retain requestId/idempotency keys for write retries.
The host backend can revoke one session or all customer sessions. Revoking the issuing API Key invalidates its customer tokens on their next request.

app/groove-session.tsTypeScript

1import { GrooveError } from "@tinkerlandai/indiana-sdk";2import { grow } from "./groove-client";3 4// Get a fresh token from your own authenticated session endpoint5let generation = 0;6let pending: { controller: AbortController; promise: Promise<void> } | undefined;7 8function refreshSession(): Promise<void> {9  if (pending) return pending.promise;10  const expected = generation;11  const controller = new AbortController();12  const promise = (async () => {13    const response = await fetch("/api/groove-session", {14      signal: controller.signal, cache: "no-store", credentials: "same-origin",15    });16    if (!response.ok) throw new Error("User is not signed in");17    const { customerToken } = await response.json();18    if (expected !== generation)19      throw new GrooveError("IDENTITY_CHANGED", "Identity changed during refresh");20    if (typeof customerToken !== "string") throw new Error("Invalid session");21    grow.identify(customerToken);22  })();23  pending = { controller, promise };24  const clear = () => { if (pending?.promise === promise) pending = undefined; };25  void promise.then(clear, clear);26  return promise;27}28 29// Refresh once and retry when the token expires (10 minutes by default)30export async function withSession<T>(call: () => Promise<T>) {31  const expected = generation;32  try {33    return await call();34  } catch (error) {35    if (!(error instanceof GrooveError) || error.code !== "UNAUTHENTICATED")36      throw error;37    if (expected !== generation) throw new GrooveError("IDENTITY_CHANGED", "Identity changed");38    await refreshSession();39    if (expected !== generation) throw new GrooveError("IDENTITY_CHANGED", "Identity changed");40    return call();41  }42}43 44// Discard the token before signing the user out of your app45export function disconnectSession() {46  generation++;47  pending?.controller.abort();48  pending = undefined;49  grow.reset(); // Discard the customer token and abort pending requests50}51 52export async function signOut() {53  disconnectSession();54  await fetch("/api/logout", { method: "POST" });55}