Skip to content

Refresh Session ​

Replaces the JWT of the current session with a new one, so the session lasts past the old JWT's exp. It does not disconnect the WebSocket or interrupt event delivery.

refreshSession does not reconnect

You never need it to recover from a drop: the SDK reattaches the same session on its own. See Session lifecycle.

Signature ​

// Callback version
fun refreshSession(token: String, callback: (Exception?) -> Unit)

// Suspend version
suspend fun refreshSession(token: String)

Parameters ​

ParameterTypeRequiredDescription
tokenStringYesA new valid JWT minted by your backend. Must contain the same sub (username) and application_id claims as the original session token.

Return Type ​

Returns void (or Promise<void> for Web). Completion indicates the session token has been updated successfully.

Usage Example ​


// Callback
client.refreshSession("token") { err ->
    when {
        err != null -> {  } // handle error
    }
}

// Coroutine
try {
    client.refreshSession("token")
}
catch (e:Error) {
    // Handle Error in creation session
}

Errors ​

This method can throw the following error types:

  • SESSION_ERROR — session:error:no-active-session when there is no session to refresh
  • TOKEN_ERROR — invalid or expired token
  • UNKNOWN_ERROR — any unmapped exception (e.g. session already deleted server-side)

Notes ​

  • Call refreshSession before the current JWT's exp. Once the JWT has expired, the session ends with onSessionError (TokenExpired).
  • The new token must be for the same user (sub claim) and application (application_id claim) as the current session.
  • It is a REST request, so it also works while the SDK is reattaching the session after a drop (connectionStatus is Connecting). The reattach then uses the new token.
  • After onSessionError there is no session to refresh, and it fails with session:error:no-active-session. Call createSession instead.

Built with VitePress.