Implementation:OpenHands OpenHands SaasNestedConversationManager Refresh Tokens

Knowledge Sources	OpenHands
Domains	Distributed_Systems, Conversation_Management
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for refreshing authentication provider tokens after runtime initialization, provided by the OpenHands enterprise conversation management layer.

Description

The _refresh_provider_tokens_after_runtime_init method ensures that all provider tokens stored in the Settings object are fresh before they are injected into the nested runtime server. It iterates over the configured provider tokens (e.g., GitHub OAuth tokens, LLM API keys), checks each for expiration proximity, and uses the TokenManager to obtain replacement tokens where needed.

The method returns a new Settings instance with updated ProviderToken values. Token secrets are wrapped in SecretStr to prevent accidental logging. If a token cannot be refreshed (e.g., the refresh token has been revoked), the method raises an error to prevent the conversation from starting with invalid credentials.

This method is called in the gap between runtime provisioning and configuration injection -- after the container is up but before credentials are pushed to it.

Usage

This is a private method called internally during the conversation initiation lifecycle. It is invoked by maybe_start_agent_loop after _create_runtime succeeds and before the nested server configuration phase begins. Direct invocation is not recommended outside the manager class.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/server/saas_nested_conversation_manager.py
• Lines: L238-332

Signature

async def _refresh_provider_tokens_after_runtime_init(
    self,
    settings: Settings,
    sid: str,
    user_id: str | None = None,
) -> Settings

Import

from enterprise.server.saas_nested_conversation_manager import SaasNestedConversationManager

I/O Contract

Inputs

Name	Type	Required	Description
settings	Settings	Yes	The current application settings containing provider tokens that may need refreshing. Tokens are stored as ProviderToken objects with expiration metadata.
sid	str	Yes	The conversation session identifier, used as a key for persisting refreshed tokens to durable storage.
user_id	None	No	The authenticated user identifier. When provided, it is used to look up user-specific refresh tokens in the token store. Defaults to None for system-level tokens.

Outputs

Name	Type	Description
return	Settings	A new Settings instance with all provider tokens refreshed. Token values are wrapped in SecretStr. The returned settings should be used for all subsequent configuration injection steps.

Usage Examples

Basic Usage

# Internal usage within SaasNestedConversationManager
# Called between runtime creation and nested server configuration

# After runtime is provisioned
runtime = await self._create_runtime(sid, user_id, settings, provider_handler)

# Refresh tokens before pushing config to the nested server
refreshed_settings = await self._refresh_provider_tokens_after_runtime_init(
    settings=settings,
    sid="conv_abc123",
    user_id="user_42",
)

# Use refreshed_settings for all subsequent operations
await self._configure_nested_server(runtime, refreshed_settings)

Handling Refresh Failures

try:
    refreshed_settings = await self._refresh_provider_tokens_after_runtime_init(
        settings=settings,
        sid=sid,
        user_id=user_id,
    )
except TokenRefreshError as e:
    # Token refresh failed; cannot proceed with stale credentials
    await self._cleanup_runtime(sid)
    raise ConversationError(f"Token refresh failed: {e}")

Related Pages

Implements Principle

• Principle:OpenHands_OpenHands_Token_Refresh