From 7358271ff88937723cd86cb46af211e5738088a1 Mon Sep 17 00:00:00 2001 From: "ekline[bot]" <202747777+ekline[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 17:52:50 +0000 Subject: [PATCH 1/3] docs: document blank connector tokens and user_verify_url exchange failure --- .../authentication/troubleshooting.mdx | 27 ++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/src/content/docs/agentkit/authentication/troubleshooting.mdx b/src/content/docs/agentkit/authentication/troubleshooting.mdx index f982f0fce..ac579e92f 100644 --- a/src/content/docs/agentkit/authentication/troubleshooting.mdx +++ b/src/content/docs/agentkit/authentication/troubleshooting.mdx @@ -191,14 +191,16 @@ Log both parameters in development. Do not expose raw `error_description` text t
`failed_to_exchange_token` after consent -Token exchange failed after the user approved access. See [Common scenarios on Configure connections](/agentkit/connections/#common-scenarios) for retry steps, status page checks, and what to send support. +Token exchange failed after the user approved access. A common cause is a missing verification redirect: the error text `user_verify_url not configured for verification redirect` means the connection uses custom user verification, but the authorization link started without a `user_verify_url`. User verification is a required security step that prevents token-theft and consent-phishing, and it is enabled by default in production. See [Verify user identity](/agentkit/user-verification/#common-scenarios) to pass `user_verify_url` or switch verification mode. + +For other exchange failures, see [Common scenarios on Configure connections](/agentkit/connections/#common-scenarios) for retry steps, status page checks, and what to send support.
Redirect URI mismatch -The redirect URI in the provider's OAuth app must match the URI shown in Scalekit exactly — protocol, host, path, and trailing slashes included. +The redirect URI in the provider's OAuth app must match the URI shown in Scalekit exactly, including protocol, host, path, and trailing slashes. 1. Open **AgentKit** > **Connections** and select the connection @@ -388,6 +390,21 @@ OAuth credentials on the connection do not match the provider's console.
+
+Connection returns an account id but tokens are blank + +A new connection returns a connected account id (for example `ca_...`) but the access token and refresh token fields come back empty. The connection is valid; the tokens are withheld on purpose. + +Scalekit does not return raw provider tokens in API responses by default. Exposing tokens in responses widens the surface for token theft, so token retrieval is disabled per account until you explicitly enable it. For most agents you never need the raw token: `execute_tool` / `executeTool` injects the current token for you, and Scalekit refreshes it automatically. Reach for raw tokens only when you call a provider API that AgentKit does not wrap. + +If your integration must read the raw token, contact [support](mailto:support@scalekit.com) to enable token retrieval for your account. Include your account id and the connection name. Once enabled, the token fields populate on the connected account. + + + +
+
Authorization succeeds but tools fail on scope @@ -417,5 +434,7 @@ When you contact [support](mailto:support@scalekit.com), include: Related guides: -- [Configure connections](/agentkit/connections/) — setup, scopes, and common OAuth errors -- [Manage connected accounts](/agentkit/connected-accounts/) — per-user connection state and credentials \ No newline at end of file +- [Configure connections](/agentkit/connections/): setup, scopes, and common OAuth errors +- [Manage connected accounts](/agentkit/connected-accounts/): per-user connection state and credentials + +{/* STYLE-CHECK: PASSED */} \ No newline at end of file From f9c6215891a0c95ccd193e13ac0a2a8ab49cbc4d Mon Sep 17 00:00:00 2001 From: "ekline[bot]" <202747777+ekline[bot]@users.noreply.github.com> Date: Fri, 3 Jul 2026 07:12:11 +0000 Subject: [PATCH 2/3] docs: remove committed STYLE-CHECK marker from AgentKit troubleshooting page ekline[bot] <202747777+ekline[bot]@users.noreply.github.com> --- src/content/docs/agentkit/authentication/troubleshooting.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/docs/agentkit/authentication/troubleshooting.mdx b/src/content/docs/agentkit/authentication/troubleshooting.mdx index ac579e92f..ca40b37ae 100644 --- a/src/content/docs/agentkit/authentication/troubleshooting.mdx +++ b/src/content/docs/agentkit/authentication/troubleshooting.mdx @@ -435,6 +435,4 @@ When you contact [support](mailto:support@scalekit.com), include: Related guides: - [Configure connections](/agentkit/connections/): setup, scopes, and common OAuth errors -- [Manage connected accounts](/agentkit/connected-accounts/): per-user connection state and credentials - -{/* STYLE-CHECK: PASSED */} \ No newline at end of file +- [Manage connected accounts](/agentkit/connected-accounts/): per-user connection state and credentials \ No newline at end of file From e25d07c4679d0635479c7a40f52969520b074f01 Mon Sep 17 00:00:00 2001 From: "ekline[bot]" <202747777+ekline[bot]@users.noreply.github.com> Date: Fri, 3 Jul 2026 08:35:34 +0000 Subject: [PATCH 3/3] docs: reframe blank-token guidance to not document raw-token retrieval Per reviewer: avoid describing a per-account flag that exposes raw provider tokens, which advertises an attackable interface. State that token retrieval is not returned by default, point agents to execute_tool/executeTool, and route genuine needs to support. Remove the raw-tokens caution Aside. ekline[bot] <202747777+ekline[bot]@users.noreply.github.com> --- .../docs/agentkit/authentication/troubleshooting.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/content/docs/agentkit/authentication/troubleshooting.mdx b/src/content/docs/agentkit/authentication/troubleshooting.mdx index ca40b37ae..942c68c55 100644 --- a/src/content/docs/agentkit/authentication/troubleshooting.mdx +++ b/src/content/docs/agentkit/authentication/troubleshooting.mdx @@ -393,15 +393,11 @@ OAuth credentials on the connection do not match the provider's console.
Connection returns an account id but tokens are blank -A new connection returns a connected account id (for example `ca_...`) but the access token and refresh token fields come back empty. The connection is valid; the tokens are withheld on purpose. +A new connection returns a connected account id (for example `ca_...`), but the access token and refresh token fields come back empty. The connection is valid. -Scalekit does not return raw provider tokens in API responses by default. Exposing tokens in responses widens the surface for token theft, so token retrieval is disabled per account until you explicitly enable it. For most agents you never need the raw token: `execute_tool` / `executeTool` injects the current token for you, and Scalekit refreshes it automatically. Reach for raw tokens only when you call a provider API that AgentKit does not wrap. +Scalekit does not return raw provider tokens in API responses by default. Exposing tokens in responses widens the surface for token theft, so token retrieval is not allowed, which keeps your connected accounts safe. Your agents should not need raw tokens: `execute_tool` / `executeTool` injects the auth context automatically during tool calling in a secure environment. -If your integration must read the raw token, contact [support](mailto:support@scalekit.com) to enable token retrieval for your account. Include your account id and the connection name. Once enabled, the token fields populate on the connected account. - - +If your use case genuinely requires raw token access, contact [support](mailto:support@scalekit.com).