fix(connect): tell users exactly which token permissions each provider needs

[claude]

Requested by boris · Slack thread

Before / After

Before: at the token-paste prompt the CLI showed a one-line hint ("create a new token ... with all permissions") and a console link. Several links were wrong (Datadog console URLs are broken for us3/us5/ap1 sites, Better Stack's Telemetry link 301s to a product page), permission lists were missing or incomplete (Honeycomb omitted two permissions the backend provably needs, so a key built from the prompt connects fine and then silently fails every query), and the MCP bearer prompt had no guidance at all.

After: every credential-paste prompt names the exact console path, the doc-verified minimum permission set (or an honest "no scopes exist, here is what the key can do"), and the expected token format, in 3-4 short lines above the hidden input. Datadog links resolve on all six sites in the picker.

How

All copy was verified against each vendor's current official docs (creation path, permission names quoted verbatim, token format) and cross-checked against what the backend clients in coreplanelabs/nominal actually call. Changes are limited to promptSecret instruction text/links in src/commands/integration/connect.ts and src/commands/cloud/connect.ts, one small datadogConsoleUrl() helper for the site-host fix, a note() before the MCP bearer prompt, and a richer usage-error hint on the PlanetScale flags-only path. No prompt flow, ordering, or backend behavior changed.

Per-provider summary

Provider	What was wrong	What it now says	Verified against
Datadog	https://app.${site}/... is a broken host for us3/us5/ap1; no scope guidance	app. prefix only for datadoghq.com / datadoghq.eu / ddog-gov.com; create the app key as a Datadog Admin (connect needs org_management), leave it unscoped; opaque hex, no prefix	Site list, API/app keys, RBAC permissions
Honeycomb	Permission list missing Run Queries (main query path silently fails post-connect) and Manage SLOs; link not region-aware	Full 8-permission set, leave Send Events and Read Service Maps off; EU link for EU region	Manage API keys, Query data API, SLOs API
Axiom	"all permissions" (over-grant); link to bare app.axiom.co	Advanced > Custom token: all datasets + Query; Datasets/Dashboards read, Monitors read+update, Notifiers create/read/delete; xaat- prefix; direct API-tokens link	Tokens, RBAC/settings
Better Stack	Telemetry link 301s to a product page; Uptime prompt pointed at the global-tokens URL; no team guidance	Both team tokens from settings/api-tokens/0, same team as your monitors; states no scope options exist and the Uptime token can create monitors/webhooks	Uptime API, Telemetry API
Devin	No warning that enterprise-scoped keys are rejected; no role guidance	Org-scoped service user, Member role (or ManageOrgSessions + ViewOrgSessions + UseDevinSessions on custom roles); cog_, shown once	Authentication, Teams quickstart
Cursor	"Cursor → Settings" is the wrong place; key_ prefix unverifiable; no warning that service account keys break connect	Dashboard > API Keys, user key not service account key, no scopes; crsr_ (older key_); GitHub App repo note kept	API docs, Cloud Agents API
Factory	No key-type or scope info	Prefer a service account key (needs Owner/Manager role); keys have no scope options; fk-, shown once	API reference, Service accounts
MCP bearer	Bare password prompt, zero guidance	Paste the bare token without "Bearer " (backend adds it); token must cover tools/list and tools/call, nothing else is called	MCP authorization spec
Cloudflare	Never said account-owned token or Super Administrator; no format hint	Account-owned token via Manage Account > Account API Tokens, Super Administrator required, don't edit the pre-filled permissions; cfat_, shown once	Account-owned tokens, Token formats
Fly.io	No token-type guidance; no format hint	Org token (needed for rollback remediation) vs read-only (fly tokens create readonly, sync/metrics only); paste including the leading FlyV1	Tokens, tokens create readonly
Render	No mention keys are unscoped/account-wide; role requirement missing	Keys have no scopes and act as you in every workspace; Developer or Admin role required (Viewer/Contributor can't read env vars/connection strings); rnd_; link opens the create panel	Authentication, Team members
Modal	Said nothing about scoping or read-only options	No scope picker, token carries the creating account's access; Team/Enterprise: Service User + Viewer role per environment	RBAC, Service users
Kubernetes	Only a Helm-agent pointer; no RBAC guidance for the uploaded kubeconfig	Warns the current-context credentials are uploaded (often cluster-admin); recommends a ServiceAccount bound cluster-wide to the read-only view ClusterRole with a long-lived token, and names what view omits	User-facing roles, ServiceAccount tokens
PlanetScale	Flags-only path errored with no pointer	Usage error now names the service-token page and the minimum accesses (read_organization, read_database, read_branch)	Service tokens

Left unchanged: GitHub, Slack, Sentry, AWS, Vercel, Supabase (browser flows, no credential paste). The Modal token-secret prompt copy was already correct.

Screenshots

What the connect prompt now shows, captured from the real CLI on this branch (post-merge with main's back-navigation flow).

Datadog

Honeycomb

Axiom

Better Stack

Devin

Cursor

Factory

MCP bearer token

Cloudflare

Fly.io

Render

Modal

Kubernetes

PlanetScale (usage-error hint on the flags-only path)

Backend findings (not addressed here, for follow-up in nominal)

• Datadog connect hard-requires org_management (Datadog Admin only). GET /api/v1/org failure is a fatal 400 in api-integrations/.../connect.ts:107-109, but validateAppKey() already returns the org name, so the /api/v1/org call could likely be dropped, removing the most privileged permission from the requirement.
• Datadog getAppKeyScopes() is fatal too: a key lacking user_app_keys yields a 500 instead of a graceful degrade (same Promise.all).
• Honeycomb connect validation only calls GET /1/auth, which requires no permission, so a key missing Run Queries connects "successfully" and then silently fails every query. Validation should exercise a permission-gated endpoint.
• Cursor connect rejects service account keys: connect.ts:459 requires self.userId, which Cursor omits for service-account keys. Could fall back to the key fingerprint like the Factory branch does.
• Cloudflare pre-filled token URL builder (cloudflare-token-url.ts:141) contains { key: "pipelines", type: "send" }; send is not one of Cloudflare's five documented type values. Also worth adding a short redirect (e.g. polylane.com/cf-token) so the CLI can link the ~13KB pre-filled dash URL directly.
• Console docs contradictions: clouds-fly.ts says "read-only token" but the backend performs image rollback writes; integrations-axiom.ts says "read access" but the client updates monitors and creates/deletes notifiers; clouds-modal.ts says tokens are unscoped, outdated since Modal shipped RBAC/Service Users; integrations-betterstack.ts may carry the same stale telemetry link the CLI had.
• PlanetScale interactive service-token prompts don't exist in the CLI (flags-only), so full paste-prompt guidance has nowhere to print until prompts are added.

🤖 Generated with Claude Code

https://claude.ai/code/session_018rJSaPdnfppLe41Lf3fkoZ

---

Generated by Claude Code

[polylane]

Warning

Polylane could not verify the production impact of this pull request.

Checked the two changed files against the resulting tree; tsc --noEmit passes clean. Only CLI prompt text, URLs, and link labels change — no API calls, control flow, or backend behavior. No production resource runs this code.

View the full analysis →

Polylane could not find the cloud resources this repository manages, so this review looked at the entire cloud account. Connect this repository to its resources and the next review will focus on exactly what this code deploys to.

_{Polylane analysed 7c4b87e for production impact.}