# ovok_sdk.auth.user_session

Canonical page: https://docs.ovok.com/python-sdk/reference/auth/user_session

The signed-in user's session and its token refresh.

## UserSession [#usersession]

```python
UserSession(
    store: SessionStore,
    endpoint: TokenEndpoint,
    settings: OvokSettings,
    clock: Clock = epoch_ms,
)
```

The signed-in user's tokens, kept in storage and refreshed a minute before they expire.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `SessionStore` |  | Where the session is kept. |
| `endpoint` | `TokenEndpoint` |  | The OAuth token endpoint used to refresh. |
| `settings` | `OvokSettings` |  | The client's settings. |
| `clock` | `Clock` | `epoch_ms` | Current time in epoch milliseconds. |

### current() [#current]

```python
current() -> Session | None
```

Return the stored session, or None when no one is signed in.

### begin() [#begin]

```python
begin(tokens: Mapping[str, Any]) -> Session
```

Start a session from a sign-in response and notify listeners.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens` | `Mapping[str, Any]` |  | The camelCase body of an Ovok sign-in route. |

**Returns**

- `Session`: The new session.

### end() [#end]

```python
end() -> None
```

Delete the session and notify listeners.

### on_change() [#on_change]

```python
on_change(listener: Callable[[], None]) -> None
```

Call `listener` whenever the session starts, refreshes or ends.

### access_token() [#access_token]

```python
access_token() -> str | None
```

Return the access token, refreshing it first when it is stale; None when signed out.

### refresh() [#refresh]

```python
refresh() -> bool
```

Exchange the refresh token for new tokens.

A refused refresh signs the user out and calls `on_unauthenticated`.

**Returns**

- `bool`: True when the session was refreshed; False when there is nothing to refresh
- `bool`: or the refresh was refused.

**Raises**

- `OvokError`: The refresh failed for another reason, such as an outage.