docs: document blank connector tokens and user_verify_url exchange failure

[ekline]

Problem

Developers integrating AgentKit outbound connectors hit three authorization failures that were under-documented in the troubleshooting guide:

1. failed_to_exchange with user_verify_url not configured for verification redirect. The troubleshooting page's failed_to_exchange_token scenario did not name user verification as a cause or link to the fix.
2. Blank tokens: a new connection returns a connected account id (e.g. ca_...) but empty access/refresh token fields. Not documented anywhere. Root cause: returning raw tokens in API responses is disabled by default for security and must be enabled per account by Scalekit.
3. Cross-account failure (OAuth app works only for the account that created it). Already well covered on the page, so no change needed.

Audience

A developer integrating AgentKit outbound connectors (intermediate) whose agent connects to third-party tools (Airtable, ZoomInfo, Google Drive) on behalf of their own and their customers' end users. Goal: authorize outbound connectors for their own and external/customer accounts and actually receive tokens back.

Gravity

HIGH. 3 distinct customers, production, recurring. Category: mixed (docs gap + product).

Scrubbed customer quotes

• "it works with the same account where the app was created, but not with other/external accounts"
• "it's returning the connection but not the tokens"
• "can we please hide/remove the pre-filled Client ID? It gives the impression that DCR is supported"

Fix (this PR)

Edited the AgentKit connection troubleshooting page only:

• Enriched the failed_to_exchange_token scenario to name the user_verify_url not configured cause, state that user verification is a required security step enabled by default in production, and link to the user verification guide.
• Added a new "Connection returns an account id but tokens are blank" scenario explaining that raw provider tokens are withheld by default for security, that execute_tool/executeTool injects tokens automatically, and how to request token retrieval via support.

Cross-account coverage already exists on the page, so it is left unchanged to keep the diff minimal.

Follow-ups / product (not docs-fixable)

• Pre-filled client_id on Scalekit-provided connectors wrongly implies DCR is supported. Consider hiding/removing it or labeling it clearly. Customer quote: "can we please hide/remove the pre-filled Client ID?"
• A hosted "connect" widget / pre-check screen appeared by default after a platform change, with no self-serve toggle (support disabled it per-environment). Add a self-serve toggle. Note: magic-link/hosted widgets work for OAuth connectors only, since non-OAuth connectors need to collect input such as API keys.
• Consider a product-side default or self-serve toggle for token retrieval so developers who genuinely need raw tokens are not blocked on support.

Preview

https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/agentkit/authentication/troubleshooting/

ekline[bot] <202747777+ekline[bot]@users.noreply.github.com>

---

📝 Created with EkLine · View session

[netlify]

✅ Deploy Preview for scalekit-starlight ready!

Name	Link
🔨 Latest commit	e25d07c
🔍 Latest deploy log	https://app.netlify.com/projects/scalekit-starlight/deploys/6a47745c00b1260008558216
😎 Deploy Preview	https://deploy-preview-819--scalekit-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 58 (🟢 up 20 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[saif-at-scalekit]

@AkshayParihar33 Please verify this content? My understanding is users' don't need to contact the scalekit support to enable token retrieval. Is that correct?

[saif-at-scalekit]

@ekline i dont think we should even put it out that there is some flag which can be enabled and raw tokens can be shared. i feel its like announcing to attackers that we have an interface layer where tokens can be pulled in. can we make it something like this rather:

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 to keep your connected accounts safe. Ideally your agents should never need the access to raw tokens: execute_tool / executeTool automatically injects the auth context during tool calling in a secure environment. If your agent's usecase must need access to raw token, contact support and can we remove this please?

Never log raw tokens or send them to a browser or client application. Keep them server-side and let Scalekit refresh them.

cc: @AkshayParihar33

[ekline]

Good call — agreed that documenting a per-account flag to pull raw tokens advertises an attackable interface. Reworded the scenario to your framing and pushed:

• Token retrieval is not allowed by default; raw tokens are not returned in API responses because that widens the surface for token theft.
• Agents should not need raw tokens — execute_tool / executeTool injects the auth context automatically during tool calling in a secure environment.
• Genuine raw-token use cases just go to support, with no self-serve enablement steps, account id, or "once enabled the fields populate" mechanics documented.
• Removed the "Handle raw tokens as secrets" caution Aside.

Updated on e25d07c4. Preview: https://deploy-preview-819--scalekit-starlight.netlify.app/agentkit/authentication/troubleshooting/

[ekline]

Done. The change is pushed to PR #819 and I replied to the reviewer inline.

What changed (PR #819)

The reviewer's concern was that documenting a per-account flag to pull raw tokens effectively advertises an attackable "tokens can be pulled here" interface. I reworked the "Connection returns an account id but tokens are blank" scenario to remove that:

Before — described a self-serve mechanism: "token retrieval is disabled per account until you explicitly enable it… contact support to enable token retrieval for your account. Include your account id and the connection name. Once enabled, the token fields populate." Plus a "Handle raw tokens as secrets" caution Aside.

After — adopts the reviewer's framing:

• Raw provider tokens are not returned by default, and token retrieval is not allowed, because exposing tokens widens the surface for token theft.
• Agents should not need raw tokens — execute_tool / executeTool injects the auth context automatically during tool calling in a secure environment.
• Genuine cases just contact support, with no enablement steps, account-id instructions, or "once enabled the fields populate" mechanics.
• Removed the raw-tokens caution Aside, as requested.

Net diff: +3/−7 lines on agentkit/authentication/troubleshooting.mdx. The pre-commit style review ran clean and preserved the security framing (no Aside re-added).

• Commit: e25d07c4 on docs/agentkit-connector-token-troubleshooting
• Reply to reviewer: discussion_r3518571874
• Preview: https://deploy-preview-819--scalekit-starlight.netlify.app/agentkit/authentication/troubleshooting/

Repo is back on a clean main. One thing worth a heads-up for the team (not a docs change): the reviewer’s note implies the raw-token retrieval path should stay strictly a support-gated exception — if product ever exposes a self-serve toggle for it, the docs stance here (“not allowed”) would need revisiting.