Set up the SDK

Your app talks to its Foundation backend through foundation-sdk — one typed client you initialize once and share everywhere.

Install

npm install foundation-sdk
# plus your auth provider:
npm install aws-amplify              # Cognito (default)
# or: npm install @auth0/auth0-spa-js   # Auth0

Initialize once

Await createFoundation(...) a single time and share the instance through your app's context or state. The returned instance is fully initialized; you do not need to await foundation.ready separately.

import { createFoundation } from 'foundation-sdk'
import { cognitoAuth } from 'foundation-sdk/cognito'

export const foundation = await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL, // dev-only, optional
  auth: cognitoAuth,
})

For Auth0, import auth0Auth from foundation-sdk/auth0 instead.

Public init headers

The configUrl points at the public init endpoint, usually https://.../api/v1/public/init. The SDK fetches that URL exactly as provided; do not append another path. If you call it directly from tooling or a non-JS client, include these request headers:

Header	Value
X-Foundation-Mvp-Tenant-Id	The same tenant id you pass as tenantId
X-Foundation-Mvp-Application-Id	The same application id you pass as appId

curl "$VITE_FOUNDATION_CONFIG_URL" \
  -H "X-Foundation-Mvp-Tenant-Id: $VITE_FOUNDATION_TENANT_ID" \
  -H "X-Foundation-Mvp-Application-Id: $VITE_FOUNDATION_APP_ID"

Use those header names exactly; the endpoint does not accept alternate tenant or application header names.

Dev vs production

	How identity is provided
Local dev	Pass configUrl, tenantId, appId (and optional dev-only baseUrl) explicitly.
Production	Foundation writes /foundation-env.json at deploy and the SDK reads it automatically — so createFoundation({ auth }) works with no identity values.

Rules that matter

• Always await createFoundation(...); do not add a second readiness wait.
• Initialize once — never a second createFoundation() call.
• Use exactly one auth provider entry point.
• baseUrl is dev-only; production must not depend on it.
• Never put private secrets in frontend code.

Reference

• SDK reference — every method
• Deploy your app — how /foundation-env.json gets written