feat: Add health check and auto-reauth controls for managed auth connections

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 112
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-b7a19ff1fbd93322c8cffcd0b397ce2536ca8bff91594e0081bd030d4bec879f.yml
-openapi_spec_hash: 490520e6f0a8b1ebc89e9c0add46082d
+openapi_spec_hash: 9dd204b37a357b19032aea9eb4496645
 config_hash: 08d55086449943a8fec212b870061a3f

src/kernel/resources/auth/connections.py

@@ -62,8 +62,10 @@ def create(
         domain: str,
         profile_name: str,
         allowed_domains: SequenceNotStr[str] | Omit = omit,
+        auto_reauth: bool | Omit = omit,
         credential: connection_create_params.Credential | Omit = omit,
         health_check_interval: int | Omit = omit,
+        health_checks: bool | Omit = omit,
         login_url: str | Omit = omit,
         proxy: connection_create_params.Proxy | Omit = omit,
         record_session: bool | Omit = omit,
@@ -105,6 +107,15 @@ def create(
               - OneLogin: \\**.onelogin.com
               - Ping Identity: _.pingone.com, _.pingidentity.com
 
+          auto_reauth: Whether to permit automatic re-authentication when a scheduled health check
+              detects an expired session. This is an opt-in flag only — it does not check
+              whether re-auth is actually feasible. Even when true, re-auth only runs when the
+              system has what it needs to perform it (for example, saved credentials for the
+              required login fields), and only after a scheduled health check detects an
+              expired session — so this flag has no effect when `health_checks` is false. When
+              false, expired sessions are marked as `NEEDS_AUTH` instead of attempting
+              re-auth. Defaults to true.
+
           credential:
               Reference to credentials for the auth connection. Use one of:
 
@@ -118,6 +129,11 @@ def create(
               depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes),
               Hobbyist: 3600 (1 hour).
 
+          health_checks: Whether to enable periodic health checks. When false, the system will not
+              automatically verify authentication status, and `auto_reauth` has no effect on
+              the automatic flow (since re-auth is only triggered by a failed scheduled health
+              check). Defaults to true.
+
           login_url: Optional login page URL to skip discovery
 
           proxy: Proxy selection. Provide either id or name. The proxy must belong to the
@@ -144,8 +160,10 @@ def create(
                     "domain": domain,
                     "profile_name": profile_name,
                     "allowed_domains": allowed_domains,
+                    "auto_reauth": auto_reauth,
                     "credential": credential,
                     "health_check_interval": health_check_interval,
+                    "health_checks": health_checks,
                     "login_url": login_url,
                     "proxy": proxy,
                     "record_session": record_session,
@@ -199,8 +217,10 @@ def update(
         id: str,
         *,
         allowed_domains: SequenceNotStr[str] | Omit = omit,
+        auto_reauth: bool | Omit = omit,
         credential: connection_update_params.Credential | Omit = omit,
         health_check_interval: int | Omit = omit,
+        health_checks: bool | Omit = omit,
         login_url: str | Omit = omit,
         proxy: connection_update_params.Proxy | Omit = omit,
         record_session: bool | Omit = omit,
@@ -220,6 +240,14 @@ def update(
         Args:
           allowed_domains: Additional domains valid for this auth flow (replaces existing list)
 
+          auto_reauth: Whether automatic re-authentication is permitted for this connection. This is an
+              opt-in flag only — it does not check whether re-auth is actually feasible. Even
+              when true, re-auth only runs when the system has what it needs to perform it
+              (for example, saved credentials for the required login fields), and only after a
+              scheduled health check detects an expired session — so this flag has no effect
+              when `health_checks` is false. When false, expired sessions detected by a health
+              check are marked as `NEEDS_AUTH` instead of attempting re-auth.
+
           credential:
               Reference to credentials for the auth connection. Use one of:
 
@@ -229,6 +257,11 @@ def update(
 
           health_check_interval: Interval in seconds between automatic health checks
 
+          health_checks: Whether periodic health checks are enabled. When set to false, the system will
+              not automatically verify authentication status, and `auto_reauth` has no effect
+              on the automatic flow (since re-auth is only triggered by a failed scheduled
+              health check).
+
           login_url: Login page URL. Set to empty string to clear.
 
           proxy: Proxy selection. Provide either id or name. The proxy must belong to the
@@ -253,8 +286,10 @@ def update(
             body=maybe_transform(
                 {
                     "allowed_domains": allowed_domains,
+                    "auto_reauth": auto_reauth,
                     "credential": credential,
                     "health_check_interval": health_check_interval,
+                    "health_checks": health_checks,
                     "login_url": login_url,
                     "proxy": proxy,
                     "record_session": record_session,
@@ -544,8 +579,10 @@ async def create(
         domain: str,
         profile_name: str,
         allowed_domains: SequenceNotStr[str] | Omit = omit,
+        auto_reauth: bool | Omit = omit,
         credential: connection_create_params.Credential | Omit = omit,
         health_check_interval: int | Omit = omit,
+        health_checks: bool | Omit = omit,
         login_url: str | Omit = omit,
         proxy: connection_create_params.Proxy | Omit = omit,
         record_session: bool | Omit = omit,
@@ -587,6 +624,15 @@ async def create(
               - OneLogin: \\**.onelogin.com
               - Ping Identity: _.pingone.com, _.pingidentity.com
 
+          auto_reauth: Whether to permit automatic re-authentication when a scheduled health check
+              detects an expired session. This is an opt-in flag only — it does not check
+              whether re-auth is actually feasible. Even when true, re-auth only runs when the
+              system has what it needs to perform it (for example, saved credentials for the
+              required login fields), and only after a scheduled health check detects an
+              expired session — so this flag has no effect when `health_checks` is false. When
+              false, expired sessions are marked as `NEEDS_AUTH` instead of attempting
+              re-auth. Defaults to true.
+
           credential:
               Reference to credentials for the auth connection. Use one of:
 
@@ -600,6 +646,11 @@ async def create(
               depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes),
               Hobbyist: 3600 (1 hour).
 
+          health_checks: Whether to enable periodic health checks. When false, the system will not
+              automatically verify authentication status, and `auto_reauth` has no effect on
+              the automatic flow (since re-auth is only triggered by a failed scheduled health
+              check). Defaults to true.
+
           login_url: Optional login page URL to skip discovery
 
           proxy: Proxy selection. Provide either id or name. The proxy must belong to the
@@ -626,8 +677,10 @@ async def create(
                     "domain": domain,
                     "profile_name": profile_name,
                     "allowed_domains": allowed_domains,
+                    "auto_reauth": auto_reauth,
                     "credential": credential,
                     "health_check_interval": health_check_interval,
+                    "health_checks": health_checks,
                     "login_url": login_url,
                     "proxy": proxy,
                     "record_session": record_session,
@@ -681,8 +734,10 @@ async def update(
         id: str,
         *,
         allowed_domains: SequenceNotStr[str] | Omit = omit,
+        auto_reauth: bool | Omit = omit,
         credential: connection_update_params.Credential | Omit = omit,
         health_check_interval: int | Omit = omit,
+        health_checks: bool | Omit = omit,
         login_url: str | Omit = omit,
         proxy: connection_update_params.Proxy | Omit = omit,
         record_session: bool | Omit = omit,
@@ -702,6 +757,14 @@ async def update(
         Args:
           allowed_domains: Additional domains valid for this auth flow (replaces existing list)
 
+          auto_reauth: Whether automatic re-authentication is permitted for this connection. This is an
+              opt-in flag only — it does not check whether re-auth is actually feasible. Even
+              when true, re-auth only runs when the system has what it needs to perform it
+              (for example, saved credentials for the required login fields), and only after a
+              scheduled health check detects an expired session — so this flag has no effect
+              when `health_checks` is false. When false, expired sessions detected by a health
+              check are marked as `NEEDS_AUTH` instead of attempting re-auth.
+
           credential:
               Reference to credentials for the auth connection. Use one of:
 
@@ -711,6 +774,11 @@ async def update(
 
           health_check_interval: Interval in seconds between automatic health checks
 
+          health_checks: Whether periodic health checks are enabled. When set to false, the system will
+              not automatically verify authentication status, and `auto_reauth` has no effect
+              on the automatic flow (since re-auth is only triggered by a failed scheduled
+              health check).
+
           login_url: Login page URL. Set to empty string to clear.
 
           proxy: Proxy selection. Provide either id or name. The proxy must belong to the
@@ -735,8 +803,10 @@ async def update(
             body=await async_maybe_transform(
                 {
                     "allowed_domains": allowed_domains,
+                    "auto_reauth": auto_reauth,
                     "credential": credential,
                     "health_check_interval": health_check_interval,
+                    "health_checks": health_checks,
                     "login_url": login_url,
                     "proxy": proxy,
                     "record_session": record_session,

src/kernel/types/auth/connection_create_params.py

@@ -40,6 +40,18 @@ class ConnectionCreateParams(TypedDict, total=False):
     - Ping Identity: _.pingone.com, _.pingidentity.com
     """
 
+    auto_reauth: bool
+    """
+    Whether to permit automatic re-authentication when a scheduled health check
+    detects an expired session. This is an opt-in flag only — it does not check
+    whether re-auth is actually feasible. Even when true, re-auth only runs when the
+    system has what it needs to perform it (for example, saved credentials for the
+    required login fields), and only after a scheduled health check detects an
+    expired session — so this flag has no effect when `health_checks` is false. When
+    false, expired sessions are marked as `NEEDS_AUTH` instead of attempting
+    re-auth. Defaults to true.
+    """
+
     credential: Credential
     """Reference to credentials for the auth connection. Use one of:
 
@@ -57,6 +69,14 @@ class ConnectionCreateParams(TypedDict, total=False):
     Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour).
     """
 
+    health_checks: bool
+    """Whether to enable periodic health checks.
+
+    When false, the system will not automatically verify authentication status, and
+    `auto_reauth` has no effect on the automatic flow (since re-auth is only
+    triggered by a failed scheduled health check). Defaults to true.
+    """
+
     login_url: str
     """Optional login page URL to skip discovery"""
 

src/kernel/types/auth/connection_update_params.py

@@ -13,6 +13,18 @@ class ConnectionUpdateParams(TypedDict, total=False):
     allowed_domains: SequenceNotStr[str]
     """Additional domains valid for this auth flow (replaces existing list)"""
 
+    auto_reauth: bool
+    """Whether automatic re-authentication is permitted for this connection.
+
+    This is an opt-in flag only — it does not check whether re-auth is actually
+    feasible. Even when true, re-auth only runs when the system has what it needs to
+    perform it (for example, saved credentials for the required login fields), and
+    only after a scheduled health check detects an expired session — so this flag
+    has no effect when `health_checks` is false. When false, expired sessions
+    detected by a health check are marked as `NEEDS_AUTH` instead of attempting
+    re-auth.
+    """
+
     credential: Credential
     """Reference to credentials for the auth connection. Use one of:
 
@@ -24,6 +36,14 @@ class ConnectionUpdateParams(TypedDict, total=False):
     health_check_interval: int
     """Interval in seconds between automatic health checks"""
 
+    health_checks: bool
+    """Whether periodic health checks are enabled.
+
+    When set to false, the system will not automatically verify authentication
+    status, and `auto_reauth` has no effect on the automatic flow (since re-auth is
+    only triggered by a failed scheduled health check).
+    """
+
     login_url: str
     """Login page URL. Set to empty string to clear."""
 

src/kernel/types/auth/managed_auth.py

@@ -166,6 +166,18 @@ class ManagedAuth(BaseModel):
     - Ping Identity: _.pingone.com, _.pingidentity.com
     """
 
+    auto_reauth: Optional[bool] = None
+    """Whether automatic re-authentication is permitted for this connection.
+
+    This is an opt-in flag only — it does not check whether re-auth is actually
+    feasible. Even when true, re-auth only runs when the system has what it needs to
+    perform it (for example, saved credentials for the required login fields), and
+    only after a scheduled health check detects an expired session — so this flag
+    has no effect when `health_checks` is false. When false, expired sessions
+    detected by a health check are marked as `NEEDS_AUTH` instead of attempting
+    re-auth.
+    """
+
     browser_session_id: Optional[str] = None
     """
     ID of the underlying browser session driving the current flow (present when flow
@@ -236,6 +248,15 @@ class ManagedAuth(BaseModel):
     Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour).
     """
 
+    health_checks: Optional[bool] = None
+    """Whether periodic health checks are enabled for this connection.
+
+    When false, the system will not automatically verify authentication status, and
+    `auto_reauth` has no effect on the automatic flow (since re-auth is only
+    triggered by a failed scheduled health check). Manually triggering a health
+    check via the API still works regardless of this setting.
+    """
+
     hosted_url: Optional[str] = None
     """URL to redirect user to for hosted login (present when flow in progress)"""
 

tests/api_resources/auth/test_connections.py

@@ -38,13 +38,15 @@ def test_method_create_with_all_params(self, client: Kernel) -> None:
             domain="netflix.com",
             profile_name="user-123",
             allowed_domains=["login.netflix.com", "auth.netflix.com"],
+            auto_reauth=True,
             credential={
                 "auto": True,
                 "name": "my-netflix-creds",
                 "path": "Personal/Netflix",
                 "provider": "my-1p",
             },
             health_check_interval=3600,
+            health_checks=True,
             login_url="https://netflix.com/login",
             proxy={
                 "id": "id",
@@ -139,13 +141,15 @@ def test_method_update_with_all_params(self, client: Kernel) -> None:
         connection = client.auth.connections.update(
             id="id",
             allowed_domains=["login.netflix.com", "auth.netflix.com"],
+            auto_reauth=True,
             credential={
                 "auto": True,
                 "name": "my-netflix-creds",
                 "path": "Personal/Netflix",
                 "provider": "my-1p",
             },
             health_check_interval=3600,
+            health_checks=True,
             login_url="https://netflix.com/login",
             proxy={
                 "id": "id",
@@ -447,13 +451,15 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) ->
             domain="netflix.com",
             profile_name="user-123",
             allowed_domains=["login.netflix.com", "auth.netflix.com"],
+            auto_reauth=True,
             credential={
                 "auto": True,
                 "name": "my-netflix-creds",
                 "path": "Personal/Netflix",
                 "provider": "my-1p",
             },
             health_check_interval=3600,
+            health_checks=True,
             login_url="https://netflix.com/login",
             proxy={
                 "id": "id",
@@ -548,13 +554,15 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) ->
         connection = await async_client.auth.connections.update(
             id="id",
             allowed_domains=["login.netflix.com", "auth.netflix.com"],
+            auto_reauth=True,
             credential={
                 "auto": True,
                 "name": "my-netflix-creds",
                 "path": "Personal/Netflix",
                 "provider": "my-1p",
             },
             health_check_interval=3600,
+            health_checks=True,
             login_url="https://netflix.com/login",
             proxy={
                 "id": "id",