# Configuration

> Constructor options, trusted base URLs, and per-instance isolation.

Source: https://maincode.com/docs/client-sdk-configuration
Section: Client SDK · Matilda documentation

---

## `MatildaClientOptions`

Extends `ClientConfig`. All fields are optional except `baseUrl`.

| Field | Type | Description |
| - | - | - |
| `baseUrl` | `string` | The Matilda API base URL. Must be absolute for auth flows. Defaults to '/api'. |
| `accessToken` | `string` | A static access token. Use this for simple setups, or use getToken for managed refresh. |
| `getToken` | `GetToken` | Dynamic token provider. Called on every request. The SDK's TokenManager implements this. |
| `apiVersion` | `string \| null` | API version sent via the X-Matilda-API-Version header. Omit to use the current version. |
| `urlPolicy` | `TrustedApiBaseUrlPolicy` | URL validation policy for trustApiBaseUrl(). |
| `publicConfigEndpoint` | `PublicConfigEndpoint` | Which public runtime config endpoint to use. |
| `getCsrfToken` | `() => string \| null` | CSRF token provider for web BFF cookie auth. |
| `reportedRequestMetadata` | `ReportedRequestMetadataConfig \| null` | SDK identification metadata. Auto-set to { sdkName: 'matilda-client', version }. |

### `TrustedApiBaseUrlPolicy`

| Field | Type | Description |
| - | - | - |
| `allowRelative` | `boolean` | Allow relative URLs (e.g. /api). |
| `allowedHosts` | `readonly string[]` | Allowlist of hostnames. |
| `allowLocalHttp` | `boolean` | Allow http\://localhost / 127.0.0.1 (development). |
| `requiredPathPrefix` | `string` | Require a specific path prefix (e.g. /api). |
| `requireHttps` | `boolean` | Enforce HTTPS (loopback exempt). |

### `PublicConfigEndpoint`

```ts
type PublicConfigEndpoint =
  | 'web-bff'
  | 'core-api-relative'
  | 'core-api-localhost'
  | 'core-api-localhost-3000'
  | 'core-api-android-emulator'
  | 'core-api-production';
```

## Environment URLs

| Environment | Base URL |
| - | - |
| Production | `https://matilda.maincode.com/api` |
| Staging | `https://staging.matilda.maincode.com/api` |

## Instance isolation

Each `Matilda` instance holds its own independent config. Multiple instances in the same process are fully isolated — constructor options and `configure()` writes are scoped to that instance.

```ts title="environments.ts"
const staging = new Matilda({ baseUrl: 'https://staging.matilda.maincode.com/api' });
const prod = new Matilda({ baseUrl: 'https://matilda.maincode.com/api' });

console.log(staging.config.baseUrl); // https://staging.matilda.maincode.com/api
console.log(prod.config.baseUrl);    // https://matilda.maincode.com/api

// Reconfiguring one never affects the other:
staging.configure({ baseUrl: 'https://override.example/api' });
console.log(staging.config.baseUrl); // https://override.example/api
console.log(prod.config.baseUrl);    // https://matilda.maincode.com/api (unchanged)
```

## `configure(options)`

Updates the instance config in place. Returns `this` for chaining.

```ts
client.configure({ accessToken: newToken }).chat.create(/* … */);
```

| Field | Type | Description |
| - | - | - |
| `options` | `MatildaClientOptions` | New config to merge. |

## `config` (getter)

Returns the current `ClientConfig`.

```ts
const cfg = client.config;
console.log(cfg.baseUrl, cfg.accessToken);
```

## `trustApiBaseUrl(rawUrl, policy?)`

Validates and brands a URL as a trusted API base URL.

| Field | Type | Description |
| - | - | - |
| `rawUrl` | `string` | The URL to validate. |
| `policy` | `TrustedApiBaseUrlPolicy` | Optional override policy. |

Returns a `TrustedApiBaseUrl` (a branded string).