> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK initialization

> window.mindset.init() and the SDK-level surface: app config, auth, and what stays at the page level.

The Mindset AI SDK is initialized once per page. After the bundle loads from your `<script>` tag, you call `window.mindset.init()` with your app UID and an authentication callback. The init function attaches runtime instances to every `<mindset-agent>` element on the page and watches for new ones added later.

Per-agent setup happens on the element itself, not here. This page covers the page-level API: the things you do once.

***

## `window.mindset.init(config)`

Initialize the SDK. Call once after the bundle loads.

**Signature:**

```ts theme={null}
window.mindset.init(config: InitConfig): Promise<void>
```

**Returns:** A promise that resolves once the SDK has set up shared resources. The agents themselves initialize in parallel. Listen for `mindset:agent-idle` on each element to know it's ready. Note that an agent configured with an icebreaker will fire that turn immediately after the first idle event. The [`sendWhenIdle` pattern](./methods.mdx#waiting-for-the-agent-to-be-ready) handles this so you don't need to track which configuration applies.

### `InitConfig`

| Field                          | Type                    | Required                       | Description                                                                                              |
| ------------------------------ | ----------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `appUid`                       | `string`                | Yes                            | Your app's UID. Available in the Agent Management Studio.                                                |
| `fetchAuthentication`          | `() => Promise<string>` | Yes (for authenticated agents) | Async callback the SDK calls to obtain a user token. See [Authentication](#authentication) below.        |
| `extendedSituationalAwareness` | `boolean`               | No                             | Lifts the situational-awareness character limit from 10,000 to 20,000 across the page. Default: `false`. |
| `theme`                        | `ThemeConfig`           | No                             | Page-level theme override. Per-element `theme` attributes override this.                                 |
| `initialQuestion`              | `string`                | No                             | Default first question used by all agents on the page. Per-element `initial-question` overrides.         |

```js theme={null}
window.mindset.init({
  appUid: 'your-app-uid',
  fetchAuthentication: async () => {
    const r = await fetch('/api/mindset-token', { credentials: 'include' });
    const { authToken } = await r.json();
    return authToken;
  },
});
```

### When to call `init`

You can call `init` before or after `<mindset-agent>` elements are in the DOM. Both orders work:

* If you init first and then add elements (common when you mount agents from a JS framework like React or Vue), the SDK's `MutationObserver` picks up elements as they're added.
* If you add elements first and then init (common with static HTML), the SDK finds existing elements and binds them.

Either way, the page-level config and per-element attributes apply at bind time. Element methods (`setPageTools`, `setSituationalAwareness`, `sendMessage`, thread CRUD, etc.) become callable after `mindset.init()` completes and the element fires `mindset:agent-idle`. See [§ When the element is ready to call](./methods.mdx#when-the-element-is-ready-to-call).

***

## Authentication

The SDK delegates auth to your `fetchAuthentication` callback. The callback returns a token your app's backend mints from `sdkusersapi`. The SDK exchanges that token for the credentials the runtime needs.

```js theme={null}
window.mindset.init({
  appUid: 'your-app-uid',
  fetchAuthentication: async () => {
    // Call your own backend, which calls sdkusersapi
    const r = await fetch('/api/mindset-token', { credentials: 'include' });
    const { authToken } = await r.json();
    return authToken;
  },
});
```

The callback runs:

* Once when the SDK first needs a token
* Again whenever the token expires and needs refreshing

You write the callback as if it always fetches fresh. The SDK handles caching and refresh timing internally.

<Note>
  **Token endpoint setup.** Setting up the backend endpoint that mints SDK tokens (calling `sdkusersapi`, configuring API keys, mapping users to Mindset AI identities) is a one-time piece of integration work covered in the existing Mindset AI auth docs.

  See the [SDK 3 Authentication guide](/deploy/sdk3/sdk3-authentication) for the end-to-end flow, and the [SDK Users API reference](/deploy/api/sdkusers-api) for the parameter-level detail.
</Note>

### Anonymous agents

If your agent is configured to allow anonymous access in the Agent Management Studio, you can omit `fetchAuthentication`. The agent will run without identifying the user. Useful for public-facing demos and unauthenticated marketing pages.

For authenticated agents, the callback is required. Without it, the agent fires `mindset:agent-error` with `code: 'agent_loading_failed'` (or `'model_loading_failed'`) instead of reaching `mindset:agent-idle`. Listen for `mindset:agent-error` during integration testing so silent auth misconfigurations are caught early.

***

## Auth state helpers

The SDK exposes Firebase-backed sign-in helpers for apps that use Mindset AI's hosted authentication. These are page-level: you call them on `window.mindset`, not on a specific agent.

| Function                                      | Returns                   | Description                                                                                         |
| --------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| `window.mindset.onAuthStateChanged(callback)` | unsubscribe function      | Fires whenever the user's auth state changes. Useful for showing or hiding agents based on sign-in. |
| `window.mindset.signInWithGoogle()`           | `Promise<UserCredential>` | Opens the Google sign-in flow.                                                                      |
| `window.mindset.signInWithMicrosoft()`        | `Promise<UserCredential>` | Opens the Microsoft sign-in flow.                                                                   |
| `window.mindset.signOut()`                    | `Promise<void>`           | Signs the user out.                                                                                 |

```js theme={null}
const unsubscribe = window.mindset.onAuthStateChanged((user) => {
  if (user) {
    showAgentPanel();
  } else {
    hideAgentPanel();
  }
});

// Later
unsubscribe();
```

If your app handles its own auth and uses `fetchAuthentication` to mint tokens server-side, you don't need these helpers.

***

## Page-level utilities

| Function                               | Description                                                                                                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `window.mindset.listWidgetTemplates()` | Returns the catalog of widget templates available to the agents on this page. Useful when you're building a UI that renders tool widgets and need to know what shapes to expect. |

***

## What lives where

| Concern                | Set on             | Example                                                           |
| ---------------------- | ------------------ | ----------------------------------------------------------------- |
| App identity           | `init` config      | `appUid`                                                          |
| User identity          | `init` config      | `fetchAuthentication`                                             |
| Page-wide defaults     | `init` config      | `extendedSituationalAwareness`, `theme`, `initialQuestion`        |
| Auth state listening   | `window.mindset.*` | `onAuthStateChanged`                                              |
| Per-agent identity     | element attribute  | `agent-uid`                                                       |
| Per-agent runtime mode | element attribute  | `headless`                                                        |
| Per-agent context      | element method     | `setSituationalAwareness`, `setPassthroughParams`, `setPageTools` |
| Per-agent turns        | element method     | `sendMessage`                                                     |
| Per-agent threads      | element method     | `newThread`, `switchThread`, etc.                                 |

The boundary: anything that varies across agents lives on the element. Anything page-wide lives on `window.mindset`.

***

## Error handling

`init` rejects if:

* `appUid` is missing or invalid
* The bundle hasn't finished loading (race condition, so use a `defer` script or call `init` from `DOMContentLoaded`)

Errors during agent loading surface on the affected element as `mindset:agent-error` with a code (e.g. `model_loading_failed`, `agent_loading_failed`) and a human-readable message. Listen on the element if you want to handle these:

```js theme={null}
agent.addEventListener('mindset:agent-error', (e) => {
  console.error(`Agent error [${e.detail.code}]: ${e.detail.message}`);
});
```