Customers and sessions

Create and update Customers, issue Customer Tokens, and handle Guests and claims after login.

API v1Updated Oct 22, 2026

Create or find a Customer

Use the verified user ID from your system as externalUserId. Calling again with the same ID returns the same Customer (created: false) and leaves its profile unchanged.

customer.tsTypeScript

1import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";2 3const indiana = createIndianaServer({4  baseUrl: process.env.INDIANA_API_URL!,5  apiKey: process.env.INDIANA_API_KEY!,6  scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },7});8 9async function main() {10  const { customer, created } = await indiana.getOrCreateCustomer({11    externalUserId: "user-42",12  });13  console.log(customer.id, created);14}15 16main().catch((error) => {17  console.error(error);18  process.exitCode = 1;19});

Update a Customer

Send only the fields to change. Generate and save a requestId per update; retrying with the same value never applies the change twice.

customer.tsTypeScript

1import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";2 3const indiana = createIndianaServer({4  baseUrl: process.env.INDIANA_API_URL!,5  apiKey: process.env.INDIANA_API_KEY!,6  scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },7});8 9export async function syncProfile(input: {10  verifiedUserId: string;11  requestId: string; // persisted before the first attempt12  plan: string;13}) {14  const { customer, changed } = await indiana.updateCustomer({15    lookup: { type: "externalUserId", value: input.verifiedUserId },16    requestId: input.requestId,17    patch: {18      attributes: { plan: input.plan },19      tagChanges: { add: ["beta"], remove: [] },20    },21  });22  return { customerId: customer.id, changed };23}

Call Indiana from the browser

After your backend verifies the login, call createCustomerSession to issue a Customer Token.
The browser calls identify(token); later requests act as that Customer.
On sign-out or account switch, the browser calls reset() and your backend calls revokeCustomerSessions.

server/session.tsTypeScript

1import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";2 3const indiana = createIndianaServer({4  baseUrl: process.env.INDIANA_API_URL!,5  apiKey: process.env.INDIANA_API_KEY!,6  scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },7});8 9// Call only after your own login check succeeds.10export async function issueCustomerToken(verifiedUserId: string) {11  const { customer } = await indiana.getOrCreateCustomer({12    externalUserId: verifiedUserId,13  });14  const { customerToken, expiresAt } = await indiana.createCustomerSession(customer.id);15  return { customerToken, expiresAt };16}

Register your website origin under SDK integration → Allowed website origins in Console.
The issuing Key needs sessions:create plus the scopes the browser uses, such as entitlements:read.
Tokens renew while in use, up to 30 days; after expiry, sign the user in again.

Support signed-out users

Generate a guestToken for the visitor, keep it in an HttpOnly cookie and exchange it for a Customer Token. After login, call claimGuestCustomer to bind it to the account.

guest.tsTypeScript

1import { createGuestToken, createIndianaServer } from "@tinkerlandai/indiana-sdk/server";2 3const indiana = createIndianaServer({4  baseUrl: process.env.INDIANA_API_URL!,5  apiKey: process.env.INDIANA_API_KEY!,6  scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },7});8 9// 1. First visit: create the guest token once and keep it in an HttpOnly cookie.10export async function startGuest(savedGuestToken?: string) {11  const guestToken = savedGuestToken ?? createGuestToken();12  await indiana.createGuestCustomer({ guestToken });13  const session = await indiana.resumeGuestSession({ guestToken });14  return { guestToken, customerToken: session.customerToken };15}16 17// 2. After your own login succeeds: bind the guest to the verified account.18export async function claimGuest(input: {19  guestToken: string;20  verifiedUserId: string;21  requestId: string;22}) {23  const { customer, switched } = await indiana.claimGuestCustomer({24    guestToken: input.guestToken,25    externalUserId: input.verifiedUserId,26    requestId: input.requestId,27  });28  const { customerToken } = await indiana.createCustomerSession(customer.id);29  return { customerToken, switched };30}

Related operations

Customers, Guests and Sessions (10): createCustomer, getCustomer, listCustomers, updateCustomer, createSession, renewSession, revokeSessions, createGuestCustomer, resumeGuestSession, claimGuestCustomer