From d811088fcd6421ef83c239bf7f74909d39308bbb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 6 Mar 2026 18:51:47 +0000 Subject: [PATCH 1/3] Add FAQ section on triggering re-authentication before health check Co-authored-by: Eric Feng --- profiles/managed-auth/faq.mdx | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/profiles/managed-auth/faq.mdx b/profiles/managed-auth/faq.mdx index 777034b5..eb68c40f 100644 --- a/profiles/managed-auth/faq.mdx +++ b/profiles/managed-auth/faq.mdx @@ -13,11 +13,34 @@ Automatic re-authentication only works when the stored credentials are complete ## How often are health checks performed? -Health checks on regular cadences based on your plan: +Health checks run on regular cadences based on your plan: - Hobbyist (1 hr) - Start-Up (15 min) - Enterprise (configurable) +## How do I trigger re-authentication before a health check runs? + +Before using a connection, you can check its `status` by calling `retrieve`. If the status is `NEEDS_AUTH` and the next health check hasn't run yet, trigger re-authentication immediately by starting a new login session with the connection id: + + +```typescript TypeScript +const state = await kernel.auth.connections.retrieve(auth.id); + +if (state.status === 'NEEDS_AUTH') { + const login = await kernel.auth.connections.login(auth.id); +} +``` + +```python Python +state = await kernel.auth.connections.retrieve(auth.id) + +if state.status == "NEEDS_AUTH": + login = await kernel.auth.connections.login(auth.id) +``` + + +This is useful when you need the connection to be authenticated right now and can't wait for the next scheduled health check. If the connection has a linked [credential](/profiles/credentials) with `can_reauth` set to `true`, the re-authentication happens automatically. Otherwise, you'll need to handle the login flow via the [Hosted UI](/profiles/managed-auth/hosted-ui) or [Programmatic](/profiles/managed-auth/programmatic) flow. + ## How do I know if a Kernel can automatically re-authenticate a connection? Check the `can_reauth` field on a connection. This boolean checks the following conditions: From 199c64fc83405cc924ba0e5ce857af30a8b53206 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 6 Mar 2026 19:13:16 +0000 Subject: [PATCH 2/3] Simplify re-auth FAQ: login is safe to call unconditionally Co-authored-by: Eric Feng --- profiles/managed-auth/faq.mdx | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/profiles/managed-auth/faq.mdx b/profiles/managed-auth/faq.mdx index eb68c40f..0bcd473d 100644 --- a/profiles/managed-auth/faq.mdx +++ b/profiles/managed-auth/faq.mdx @@ -20,26 +20,19 @@ Health checks run on regular cadences based on your plan: ## How do I trigger re-authentication before a health check runs? -Before using a connection, you can check its `status` by calling `retrieve`. If the status is `NEEDS_AUTH` and the next health check hasn't run yet, trigger re-authentication immediately by starting a new login session with the connection id: +If you can't wait for the next scheduled health check, you can trigger re-authentication immediately by calling `login` with the connection id. Calling `login` on a connection that's already authenticated returns immediately without re-triggering the auth flow, so it's safe to call before every use: ```typescript TypeScript -const state = await kernel.auth.connections.retrieve(auth.id); - -if (state.status === 'NEEDS_AUTH') { - const login = await kernel.auth.connections.login(auth.id); -} +await kernel.auth.connections.login(auth.id); ``` ```python Python -state = await kernel.auth.connections.retrieve(auth.id) - -if state.status == "NEEDS_AUTH": - login = await kernel.auth.connections.login(auth.id) +await kernel.auth.connections.login(auth.id) ``` -This is useful when you need the connection to be authenticated right now and can't wait for the next scheduled health check. If the connection has a linked [credential](/profiles/credentials) with `can_reauth` set to `true`, the re-authentication happens automatically. Otherwise, you'll need to handle the login flow via the [Hosted UI](/profiles/managed-auth/hosted-ui) or [Programmatic](/profiles/managed-auth/programmatic) flow. +If the connection has a linked [credential](/profiles/credentials) with `can_reauth` set to `true`, the re-authentication happens automatically. Otherwise, you'll need to handle the login flow via the [Hosted UI](/profiles/managed-auth/hosted-ui) or [Programmatic](/profiles/managed-auth/programmatic) flow. ## How do I know if a Kernel can automatically re-authenticate a connection? From 6943e33471c1ad924c24d2fb7a657fb7d6410d6e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 6 Mar 2026 21:36:10 +0000 Subject: [PATCH 3/3] Match re-auth FAQ tone with rest of page Co-authored-by: Eric Feng --- profiles/managed-auth/faq.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/profiles/managed-auth/faq.mdx b/profiles/managed-auth/faq.mdx index 0bcd473d..2003fe35 100644 --- a/profiles/managed-auth/faq.mdx +++ b/profiles/managed-auth/faq.mdx @@ -20,7 +20,7 @@ Health checks run on regular cadences based on your plan: ## How do I trigger re-authentication before a health check runs? -If you can't wait for the next scheduled health check, you can trigger re-authentication immediately by calling `login` with the connection id. Calling `login` on a connection that's already authenticated returns immediately without re-triggering the auth flow, so it's safe to call before every use: +Call `login` with the connection id. If the connection is already authenticated, `login` returns immediately. If it needs re-authentication and has a linked [credential](/profiles/credentials) with `can_reauth` set to `true`, Kernel re-authenticates automatically. ```typescript TypeScript @@ -32,7 +32,7 @@ await kernel.auth.connections.login(auth.id) ``` -If the connection has a linked [credential](/profiles/credentials) with `can_reauth` set to `true`, the re-authentication happens automatically. Otherwise, you'll need to handle the login flow via the [Hosted UI](/profiles/managed-auth/hosted-ui) or [Programmatic](/profiles/managed-auth/programmatic) flow. +If the login flow requires human input, handle it via the [Hosted UI](/profiles/managed-auth/hosted-ui) or [Programmatic](/profiles/managed-auth/programmatic) flow. ## How do I know if a Kernel can automatically re-authenticate a connection?