# SurrealSession

The SurrealSession class exposes querying and authentication with isolated per-session state.

`SurrealSession` is the base class of [`SurrealClient`](/docs/reference/kotlin/api/core/surreal-client.md) and the type returned by [`.newSession()`](/docs/reference/kotlin/api/core/surreal-client.md#new-session). It exposes the full querying, authentication, and CRUD API with state - authentication, namespace, database, and parameters - isolated to that session. See [Multiple sessions](/docs/reference/kotlin/concepts/multiple-sessions.md) for the concept.

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

---

## Shared API

Because [`SurrealClient`](/docs/reference/kotlin/api/core/surreal-client.md) extends `SurrealSession`, every session - root or child - provides the same methods documented on the client:

- Connection: [`.use()`](/docs/reference/kotlin/api/core/surreal-client.md#use), [`.ping()`](/docs/reference/kotlin/api/core/surreal-client.md#ping), [`.version()`](/docs/reference/kotlin/api/core/surreal-client.md#version)
- Authentication: [`.signin()`](/docs/reference/kotlin/api/core/surreal-client.md#signin), [`.signup()`](/docs/reference/kotlin/api/core/surreal-client.md#signup), [`.authenticate()`](/docs/reference/kotlin/api/core/surreal-client.md#authenticate), [`.auth()`](/docs/reference/kotlin/api/core/surreal-client.md#auth), [`.invalidate()`](/docs/reference/kotlin/api/core/surreal-client.md#invalidate), [`.reset()`](/docs/reference/kotlin/api/core/surreal-client.md#reset)
- Queries: [`.query()`](/docs/reference/kotlin/api/core/surreal-client.md#query), [`.queryAs<T>()`](/docs/reference/kotlin/api/core/surreal-client.md#query-as), [`.let()`](/docs/reference/kotlin/api/core/surreal-client.md#let), [`.unset()`](/docs/reference/kotlin/api/core/surreal-client.md#unset)
- CRUD builders: [`.select()`](/docs/reference/kotlin/api/core/surreal-client.md#select), [`.create()`](/docs/reference/kotlin/api/core/surreal-client.md#create), [`.update()`](/docs/reference/kotlin/api/core/surreal-client.md#update), [`.upsert()`](/docs/reference/kotlin/api/core/surreal-client.md#upsert), [`.merge()`](/docs/reference/kotlin/api/core/surreal-client.md#merge), [`.patch()`](/docs/reference/kotlin/api/core/surreal-client.md#patch), [`.delete()`](/docs/reference/kotlin/api/core/surreal-client.md#delete), [`.relate()`](/docs/reference/kotlin/api/core/surreal-client.md#relate), [`.insert()`](/docs/reference/kotlin/api/core/surreal-client.md#insert)
- Live queries: [`.live()`](/docs/reference/kotlin/api/core/surreal-client.md#live), [`.kill()`](/docs/reference/kotlin/api/core/surreal-client.md#kill)

## Session state accessors

<table>
    <thead>
        <tr><th>Method</th><th>Type</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr><td><code>.namespace()</code></td><td><code>String?</code></td><td>The session's current namespace.</td></tr>
        <tr><td><code>.database()</code></td><td><code>String?</code></td><td>The session's current database.</td></tr>
        <tr><td><code>.accessToken()</code></td><td><code>String?</code></td><td>The session's current access token, if authenticated.</td></tr>
    </tbody>
</table>

## Creating and closing sessions

```kotlin title="Example"
val session = client.newSession()
session.signin(buildJsonObject { put("user", "a"); put("pass", "a") })
session.use("acme", "main")

// ... use the session ...

client.closeSession(session)
```

## Transactions

Transactions are started on a session via the [`transaction { }`](/docs/reference/kotlin/api/core/transaction.md#transaction-block) and [`beginTransaction()`](/docs/reference/kotlin/api/core/transaction.md#begin-transaction) extension functions. See the [Transaction reference](/docs/reference/kotlin/api/core/transaction.md).

## Learn more

- [SurrealClient API reference](/docs/reference/kotlin/api/core/surreal-client.md)
- [Multiple sessions](/docs/reference/kotlin/concepts/multiple-sessions.md)
- [Transaction reference](/docs/reference/kotlin/api/core/transaction.md)