---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk/interfaces/EnginexClientOptions.md
---
[Reference](../../../index.md) / [@getenginex/sdk](../index.md) / EnginexClientOptions

# EnginexClientOptions

Options of [createEnginexClient](../functions/createEnginexClient.md).

## Properties

### autoRefresh?

> `optional` **autoRefresh?**: `boolean`

Automatic token renewal. Default: `true`. With `false`, neither the proactive refresh (before
a request, when the access token is close to expiring) nor the reactive one (after a 401) calls
`POST /auth/refresh`: the stored access token is used as is and a 401 reaches the caller unrepaired
(`auth: 'optional'` still retries without a token), without clearing the session or calling
`onSessionExpired`. Use it on server clients (RSC/SSR): renewal is left to the browser
or a Route Handler — see [Session and tokens](/concepts/session). With `sessionOwner: 'app'`,
the default becomes `false` and an explicit `true` is rejected on creation.

***

### baseUrl?

> `optional` **baseUrl?**: `string`

Gateway origin. Default `''` (same-origin: the app proxies `/api` to the gateway).
Outside the browser it must be absolute, e.g. `https://gateway.operator.com`. Origin only: the SDK
appends `/api/v1`; a path, query, fragment and credentials in the URL are rejected with
`CONFIGURATION_ERROR` when the client is created.

***

### fetch?

> `optional` **fetch?**: {(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }

`fetch` implementation. Default: `globalThis.fetch`.

#### Call Signature

> (`input`, `init?`): `Promise`<`Response`>

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch)

##### Parameters

###### input

`URL` | `RequestInfo`

###### init?

`RequestInit`

##### Returns

`Promise`<`Response`>

#### Call Signature

> (`input`, `init?`): `Promise`<`Response`>

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch)

##### Parameters

###### input

`string` | `URL` | `Request`

###### init?

`RequestInit`

##### Returns

`Promise`<`Response`>

***

### hooks?

> `optional` **hooks?**: [`EnginexClientHooks`](EnginexClientHooks.md)

Observability hooks (logging, metrics, tracing): `onRequest`/`onResponse` on each
attempt (the initial one and the retry after a renewed 401) and `onError` once per failed
call, with the final error. They never receive headers, tokens, body or the query string — see
[Extensibility](/concepts/extensibility).

***

### locale?

> `optional` **locale?**: `string`

Language sent in `Accept-Language`, e.g. `pt-BR`.

***

### onAccessTokenRejected?

> `optional` **onAccessTokenRejected?**: () => `void`

Only with `sessionOwner: 'app'`: called when the gateway refuses (401) the current access token on a
public call (a 401 for the token: without a code, as the gateway's auth middleware answers, or with
`TOKEN_EXPIRED`/`TOKEN_STALE`; never a 401 with another code, e.g. `INVALID_CREDENTIALS` for a wrong current
password), so the app can renew the session and store the new tokens in the `tokenStore` — also
on an optional-auth call (e.g. `config.get`), even when the retry without a token
succeeds. It does not fire after `client.dispose()`. With no
arguments, via `safeCall` (an exception here does not change the call's error). It notifies once per
token: a burst of 401s with the same token notifies only once, and a late 401 for a token that
was already swapped in the `tokenStore` does not notify (the request is retried with the current token). A new token
that is also refused notifies again.
It never fires without a token (the `UNAUTHENTICATED` before sending). The `onError` hook remains
for observability, one per failed call.

#### Returns

`void`

#### Throws

`CONFIGURATION_ERROR` on creation, if given with `sessionOwner: 'sdk'`
(there, use `onSessionExpired`).

#### Example

```ts
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })
```

***

### onSessionChange?

> `optional` **onSessionChange?**: (`session`) => `void`

Called when the session changes (login, refresh, logout, another tab).

#### Parameters

##### session

[`Session`](Session.md)

#### Returns

`void`

***

### onSessionExpired?

> `optional` **onSessionExpired?**: () => `void`

Called when the session expires and could not be renewed. Only with `sessionOwner: 'sdk'` (the
default): with `'app'` the SDK neither renews nor clears the session — see `onAccessTokenRejected`.

#### Returns

`void`

***

### onValidationIssue?

> `optional` **onValidationIssue?**: (`issue`) => `void`

Called when a response does not match the schema (`'warn'` mode). Without it, `'warn'` mode
still warns by default: once per route, via `console.warn`, with only the route and the
field paths — never the response values.

#### Parameters

##### issue

[`ValidationIssue`](ValidationIssue.md)

#### Returns

`void`

***

### sessionOwner?

> `optional` **sessionOwner?**: `"app"` | `"sdk"`

Who owns the session (stores and renews the tokens). Default: `'sdk'`.

* `'sdk'`: the SDK stores the tokens on login, renews them (`autoRefresh`) and clears them on logout or when
  the renewal is refused (`onSessionExpired`).
* `'app'`: the app already has its own authentication and stores the tokens in the `tokenStore` itself.
  The SDK only reads the `tokenStore` to sign the requests and build `session.get()`: it never
  renews (`autoRefresh` becomes `false`), and `auth.login`/`auth.logout` reject with
  `CONFIGURATION_ERROR` without a request. A 401 reaches the caller unrepaired; to renew, use
  `onAccessTokenRejected`. Exception: if the app already swapped the token in the `tokenStore` while the request
  was in flight, the SDK retries once with the current token (without renewing or storing).

#### Throws

`CONFIGURATION_ERROR` on creation, with `'app'` and `autoRefresh: true`.

#### Example

```ts
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })
```

***

### tenantHost?

> `optional` **tenantHost?**: `string`

Operator domain (tenant), sent in `X-Original-Host`. Required outside the browser.
In the browser, the header only goes on same-origin calls (default: `location.host`); on
cross-origin calls it is never sent, even with `tenantHost`, because the gateway's CORS rejects it.

***

### timeoutMs?

> `optional` **timeoutMs?**: `number`

Timeout in ms per attempt. Default: 20 000. The retry after a 401 (with the renewed token)
has its own timeout, as does the refresh.

***

### tokenStore?

> `optional` **tokenStore?**: [`TokenStore`](TokenStore.md)

Where to keep the tokens. Default: [memoryTokenStore](../functions/memoryTokenStore.md).

***

### validation?

> `optional` **validation?**: [`ValidationMode`](../type-aliases/ValidationMode.md)

How to handle responses outside the schema. Default: `'warn'` (only the diverging field arrives as it came;
a root of another type throws `VALIDATION_ERROR`). See [ValidationMode](../type-aliases/ValidationMode.md).

***

### webSocket?

> `optional` **webSocket?**: [`WebSocketLike`](../type-aliases/WebSocketLike.md)

WebSocket implementation for realtime. Default: `globalThis.WebSocket` (browser, Node 22+).
With neither, realtime stays `'unavailable'` and `subscribe` becomes a no-op. Outside the browser, the
gateway requires the `Origin` header of the operator's site, which Node does not send: pass a constructor
that adds it (see [WebSocketLike](../type-aliases/WebSocketLike.md)).

***

### wsUrl?

> `optional` **wsUrl?**: `string`

Gateway WebSocket URL for `@getenginex/sdk/realtime`, e.g. `wss://gateway.operator.com/ws`.
Without it, derived from `baseUrl` (`http→ws`, `https→wss`, `+ /ws`) or, without `baseUrl`, from the page
origin. The SDK appends `?token=` with the access token; never include a token here.
