# SurrealClientConfig

Configuration options for the SurrealDB Kotlin client, including reconnection and authentication.

`SurrealClientConfig` configures a [`SurrealClient`](/docs/reference/kotlin/api/core/surreal-client.md). The only required field is `url`; everything else has a sensible default.

**Source:** [surrealdb.kotlin](https://github.com/surrealdb/surrealdb.kotlin)

```kotlin title="Import"
import com.surrealdb.kotlin.SurrealClientConfig
```

---

## Fields

<table>
    <thead>
        <tr><th>Field</th><th>Type</th><th>Default</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr>
            <td><code>url</code> _(required)_</td>
            <td><code>String</code></td>
            <td>-</td>
            <td>The connection URL. The scheme (<code>ws</code>/<code>wss</code>/<code>http</code>/<code>https</code>) selects the transport.</td>
        </tr>
        <tr>
            <td id="json"><code>json</code></td>
            <td><code>Json</code></td>
            <td>lenient</td>
            <td>The <code>kotlinx.serialization</code> instance used for encoding and decoding.</td>
        </tr>
        <tr>
            <td><code>autoConnect</code></td>
            <td><code>Boolean</code></td>
            <td><code>true</code></td>
            <td>Connect lazily on the first request.</td>
        </tr>
        <tr>
            <td><code>autoAuthenticate</code></td>
            <td><code>Boolean</code></td>
            <td><code>false</code></td>
            <td>Authenticate automatically using <code>credentialProvider</code> on connect and reconnect.</td>
        </tr>
        <tr>
            <td><code>credentialProvider</code></td>
            <td><code>(suspend () -&gt; SurrealAuthInput?)?</code></td>
            <td><code>null</code></td>
            <td>Supplies credentials for automatic authentication and token renewal.</td>
        </tr>
        <tr>
            <td><code>requestTimeoutMillis</code></td>
            <td><code>Long</code></td>
            <td><code>30_000</code></td>
            <td>Per-request timeout in milliseconds.</td>
        </tr>
        <tr>
            <td><code>reconnect</code></td>
            <td><code>ReconnectConfig</code></td>
            <td><code>ReconnectConfig()</code></td>
            <td>WebSocket reconnection behaviour.</td>
        </tr>
        <tr>
            <td><code>tokenRenewalLeadMillis</code></td>
            <td><code>Long</code></td>
            <td><code>60_000</code></td>
            <td>How long before token expiry to renew, in milliseconds.</td>
        </tr>
        <tr>
            <td><code>httpClientFactory</code></td>
            <td><code>((SurrealClientConfig) -&gt; HttpClient)?</code></td>
            <td><code>null</code></td>
            <td>Supplies a custom Ktor <code>HttpClient</code>.</td>
        </tr>
    </tbody>
</table>

```kotlin title="Example"
import com.surrealdb.kotlin.SurrealAuthInput
import com.surrealdb.kotlin.SurrealClientConfig
import com.surrealdb.kotlin.engine.ReconnectConfig
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

val config = SurrealClientConfig(
    url = "wss://example.com",
    requestTimeoutMillis = 30_000,
    autoAuthenticate = true,
    tokenRenewalLeadMillis = 60_000,
    reconnect = ReconnectConfig(enabled = true, multiplier = 1.5),
    credentialProvider = {
        SurrealAuthInput.SignIn(buildJsonObject {
            put("user", "root")
            put("pass", "root")
        })
    },
)
```

---

## `ReconnectConfig` {#reconnect-config}

Controls exponential-backoff reconnection on the WebSocket transport.

```kotlin title="Import"
import com.surrealdb.kotlin.engine.ReconnectConfig
```

<table>
    <thead>
        <tr><th>Field</th><th>Type</th><th>Default</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr><td><code>enabled</code></td><td><code>Boolean</code></td><td><code>true</code></td><td>Whether reconnection is attempted.</td></tr>
        <tr><td><code>initialDelayMillis</code></td><td><code>Long</code></td><td><code>250</code></td><td>Delay before the first retry.</td></tr>
        <tr><td><code>maxDelayMillis</code></td><td><code>Long</code></td><td><code>30_000</code></td><td>Maximum delay between retries.</td></tr>
        <tr><td><code>multiplier</code></td><td><code>Double</code></td><td><code>1.5</code></td><td>Backoff multiplier applied each attempt.</td></tr>
        <tr><td><code>maxAttempts</code></td><td><code>Int?</code></td><td><code>null</code></td><td>Maximum attempts; <code>null</code> retries indefinitely.</td></tr>
    </tbody>
</table>

---

## `SurrealAuthInput` {#surreal-auth-input}

A sealed interface describing how `credentialProvider` should authenticate.

```kotlin title="Import"
import com.surrealdb.kotlin.SurrealAuthInput
```

<table>
    <thead>
        <tr><th>Variant</th><th>Payload</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr><td><code>SurrealAuthInput.SignIn</code></td><td><code>params: JsonObject</code></td><td>Sign in with credentials.</td></tr>
        <tr><td><code>SurrealAuthInput.Token</code></td><td><code>token: String</code></td><td>Authenticate with an existing token.</td></tr>
    </tbody>
</table>

## Learn more

- [SurrealClient API reference](/docs/reference/kotlin/api/core/surreal-client.md)
- [Connecting to SurrealDB](/docs/reference/kotlin/concepts/connecting-to-surrealdb.md)
- [Authentication](/docs/reference/kotlin/concepts/authentication.md)