# Set up the SDK

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

## Install

```bash
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.

```ts
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.

## 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(...)`.
- 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](/api/sdk) — every method
- [Deploy your app](/build/deploy) — how `/foundation-env.json` gets written