docs: document Kiro API-key MCP failure and GitHub login workaround (upstream #11777) #1576

Description

The Kiro authentication guide recommends KIRO_API_KEY as the default zero-touch setup, but an upstream Kiro bug can leave an otherwise functioning ACP agent without MCP or web tools.

Please document the affected behavior and a tested GitHub OAuth login workaround while the upstream issue remains unresolved.

Upstream tracking

• Bug acknowledged by Kiro: kiro-cli headless with API key: GetProfile returns "User is not authorized to access this feature", governance fails, MCP and web tools disabled (Pro, Google sign-in) kirodotdev/Kiro#11777
• Our structured reproduction and authentication comparison on Kiro CLI 2.33.1: kiro-cli headless with API key: GetProfile returns "User is not authorized to access this feature", governance fails, MCP and web tools disabled (Pro, Google sign-in) kirodotdev/Kiro#11777 (comment)

The upstream report originally used 2.27.1. We reproduced the same failure path on 2026-10-23 with 2.33.1.

Current documentation and image behavior

• docs/kiro.md — Authentication recommends API key authentication and labels OAuth device flow as “Legacy.”
• Several channel guides also show [agent].env forwarding KIRO_API_KEY.
• nightly-build.yml deliberately tracks vendor-latest CLIs and documents that nightly has no compatibility guarantee. A new nightly image can therefore pick up upstream authentication regressions even when the operator has not changed OpenAB configuration.

The documentation gap is that users following the recommended authentication path have no nearby warning explaining why chat can work while MCP is disabled.

Reproduction and evidence

Environment

• Linux container on Zeabur.
• Image channel: ghcr.io/openabdev/openab:nightly-kiro.
• Bundled Kiro CLI: 2.33.1.
• OpenAB launches kiro-cli acp --trust-all-tools.
• API key explicitly forwarded through [agent].env.
• AgentMemory stdio MCP server configured in ~/.kiro/settings/mcp.json.

API key authentication

whoami reported API key authentication and the account email, but GetProfile on the US commercial endpoint returned HTTP 400:

AccessDeniedException
User is not authorized to access this feature.

Kiro then logged:

GetProfile failed on all endpoints for API key
Failed to get governance config from API — MCP disabled, web tools disabled

ACP emitted _kiro.dev/mcp/governance_disabled with apiFailure: true. The debug state included mcp_enabled=false and is_enterprise=false.

A standalone MCP client using the same required environment could initialize the server, list 53 tools, and successfully call memory_recall. This isolated the Kiro loading failure from MCP executable, authentication, and connectivity problems.

Suggested Change

1. Add a temporary known-issue notice beside the API key recommendation

Link upstream #11777 and state the observed affected version, rather than claiming all API keys or all Kiro versions are broken.

Explain that successful whoami or ordinary chat does not establish that profile/governance checks or MCP initialization succeeded.

GitHub OAuth login should be described as a currently tested workaround for this failure, even if API keys remain the preferred unattended setup once the upstream bug is fixed.

2. Document the verified workaround

For an affected personal-account deployment that can use interactive login:

1. Run the official device login flow inside the persistent agent home, as the agent user, with KIRO_API_KEY absent from the login process:

   env -u KIRO_API_KEY kiro-cli login --use-device-flow

   In the interactive menu, explicitly select Use with GitHub, then complete authorization with the intended GitHub account. Do not add --license free in this procedure: the provider must be selected from the menu. The final deployed and re-tested provider was GitHub. Document the appropriate approved flow separately for other providers.

2. Complete GitHub browser authorization. Verify the intended identity without the API key override:

   env -u KIRO_API_KEY kiro-cli whoami

   Confirm that the output says Logged in with GitHub, rather than relying on the email alone.

3. Stop passing KIRO_API_KEY into the actual agent subprocess. Remove only that key from [agent].env and, where applicable, inherit_env or a wrapper that reintroduces it. Preserve unrelated environment variables.

   Unsetting the key only in the login shell is insufficient if OpenAB injects it again when spawning Kiro.

4. Persist the Kiro authentication state. The guide already lists ~/.kiro/ and ~/.local/share/kiro-cli/; the workaround should explicitly reference those paths.

5. Restart OpenAB and create a fresh ACP session so existing API-key-authenticated processes are replaced.

6. Verify MCP initialization and an actual read-only tool call.

In our deployment, the service-level key was retained but no longer forwarded to Kiro. If a deployment regenerates config.toml, its generation source must not silently restore the override.

3. Add a short nightly troubleshooting note

Ask reports to include the image tag/digest and kiro-cli --version. Explain that floating nightly tags follow upstream CLI changes.

An immutable nightly snapshot/digest can preserve a previously verified environment. Do not recommend a specific downgrade or claim stable/beta is unaffected without testing it.

Workaround verification

After logging out the previous session and switching to GitHub login, whoami reported Logged in with GitHub. The same email was reported as under API key authentication:

• Kiro remained on 2.33.1.
• After restarting the container, the persistent configuration still excluded the API key override, and whoami continued to report Logged in with GitHub.
• A fresh ACP session emitted _kiro.dev/mcp/server_initialized for AgentMemory and Context7.
• Kiro actually called memory_slot_list and memory_recall; both completed successfully.
• The test prompt ended with stopReason: end_turn.

Only these two tools were execution-tested. Web tools were not execution-tested.

Model access and entitlements were not exhaustively compared after GitHub login. The documentation should not promise identical access merely because the email matches.

Scope and acceptance criteria

• Add the known-issue notice and upstream link to docs/kiro.md.
• Document the workaround, including subprocess environment precedence and persistent authentication state.
• Link relevant channel/deployment examples to the central authentication caveat.
• Include nightly version diagnostics and the actual-tool-call verification step.
• Track upstream resolution and revisit the temporary notice after testing a fixed Kiro version.

This request is for documentation and operational guidance. It does not propose bypassing governance, patching Kiro binaries, or changing OpenAB's default image channel.