# Client Options (/docs/client-options)



All options are optional.

## Client options [#client-options]

`createClient(options)`

### Connection [#connection]

| Option        | Default                                        | Description                                                                                                        |
| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `baseUrl`     | env var, else page origin                      | Prefix for relative URLs. See [environment variables](/docs/frameworks#setting-baseurl-with-environment-variables) |
| `timeout`     | `30000`                                        | Timeout per attempt, in ms. `0` disables it                                                                        |
| `headers`     | `{}`                                           | Added to every request                                                                                             |
| `credentials` | `"same-origin"`, or `"include"` in cookie mode | Passed to `fetch`                                                                                                  |
| `authOrigins` | `[]`                                           | Other origins allowed to receive the token and CSRF header                                                         |
| `plugins`     | `[]`                                           | See [Plugins](/docs/plugins)                                                                                       |

### Errors and logging [#errors-and-logging]

| Option       | Default        | Description                                                              |
| ------------ | -------------- | ------------------------------------------------------------------------ |
| `throwError` | `true`         | Throw `ApiError` on failure. `false` returns `{ status: false }` instead |
| `onError`    | –              | `(res) => void`, called for every failed request                         |
| `onLog`      | `console.info` | Receives a log entry for requests sent with `log: true`                  |

### Auth [#auth]

| Option               | Default           | Description                                                                                          |
| -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `authMode`           | `"header"`        | `"header"` (bearer token) or `"cookie"` (httpOnly cookies)                                           |
| `storage`            | `"memory"`        | `"memory"`, `"session"`, `"local"`, `"cookie"` or your own adapter                                   |
| `storageKey`         | `"apiclient"`     | Prefix for storage keys and the tab channel                                                          |
| `loginUrl`           | `"/auth/login"`   | Used by `api.login()`                                                                                |
| `refreshUrl`         | `"/auth/refresh"` | Used for token refresh                                                                               |
| `logoutUrl`          | `"/auth/logout"`  | Used by `api.logout()`                                                                               |
| `refreshSkewMs`      | `30000`           | Refresh this long before the token expires. `0` disables it                                          |
| `extractTokens`      | built-in          | Where tokens are in the response. See [custom token shapes](/docs/token-refresh#custom-token-shapes) |
| `buildRefreshBody`   | `{ refresh }`     | Body of the refresh request                                                                          |
| `exposeTokens`       | `false`           | Allow `api.getAccessToken()`. See [WebSockets](/docs/websockets)                                     |
| `onAuthStateChanged` | –                 | `(state) => void` on every auth change                                                               |
| `onAuthFailure`      | –                 | Session ended: refresh rejected or logged out                                                        |

### CSRF (cookie mode) [#csrf-cookie-mode]

| Option           | Default          | Description                                                         |
| ---------------- | ---------------- | ------------------------------------------------------------------- |
| `xsrfCookieName` | –                | Cookie to read the CSRF token from                                  |
| `xsrfHeaderName` | `"X-CSRF-Token"` | Header to send it in                                                |
| `getCsrfToken`   | –                | `() => string \| Promise<string>`. Takes precedence over the cookie |

### Runtime [#runtime]

| Option     | Default | Description                                                                                 |
| ---------- | ------- | ------------------------------------------------------------------------------------------- |
| `worker`   | `true`  | Run requests in a Web Worker                                                                |
| `multiTab` | `true`  | Sync auth between tabs                                                                      |
| `cancel`   | `false` | `true`, or `{ methods, takeLatest, throwOnCancel }`. See [Cancellation](/docs/cancellation) |

## Per-request options [#per-request-options]

The last argument of `get`, `post`, `put`, `patch` and `delete`. These override the client options for one call.

| Option              | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `params`            | Query-string parameters. Nested objects and arrays are supported    |
| `addTemplateToUrl`  | Fill `{placeholders}`: `"/users/{id}"` + `{ id: 7 }`                |
| `addToUrl`          | Append path segments                                                |
| `headers`           | Extra headers                                                       |
| `timeout`           | Timeout for this call                                               |
| `baseUrl`           | Different base URL for this call                                    |
| `responseType`      | `"auto"` (default), `"json"`, `"text"`, `"blob"` or `"arrayBuffer"` |
| `throwError`        | Override the client setting                                         |
| `skipAuth`          | Don't send the token                                                |
| `refreshTokenCheck` | `false` skips 401 → refresh → retry                                 |
| `uploadSkewMs`      | Refresh first if the token expires within this many ms              |
| `fullData`          | Keep the whole body in `data`, don't unwrap `{ data }`              |
| `stringifyBody`     | `false` sends a plain-object body as-is                             |
| `beforeFunc`        | Transform the body before sending                                   |
| `afterFunc`         | Transform the payload on success                                    |
| `hideErrorMessage`  | Don't call `onError` for this request                               |
| `log`               | Log this request through `onLog`                                    |
| `cancelable`        | Opt this request in or out of cancellation                          |
| `cancelKey`         | Name to cancel this request by                                      |
| `cancelGroup`       | Tags to cancel several requests together                            |
| `takeLatest`        | Cancel the previous request with the same key                       |
| `throwOnCancel`     | Throw instead of resolving when canceled                            |

Native `fetch` options such as `signal`, `cache`, `mode` and `keepalive` pass straight through.