OmniRoute/docs/guides/KIRO_SETUP.md

title

title
Kiro Setup Guide

Kiro Setup Guide

This guide covers adding Kiro (AWS-hosted AI coding assistant) accounts to OmniRoute, with a focus on running multiple accounts simultaneously without session conflicts.

---

Background: Why Kiro Accounts Can Conflict

Kiro's backend uses AWS SSO OIDC client registrations to track active sessions. The critical constraint: each OIDC client registration supports only one active session at a time. When a second device or user authenticates using the same registered client, the backend invalidates the first account's refresh token.

This is the same mechanism that causes problems when running kiro-cli login on a machine where another Kiro account is already signed in — the new login revokes the first account's token.

---

How OmniRoute Solves This (v3.8.0+)

Starting with v3.8.0, OmniRoute calls registerClient() (AWS SSO OIDC) during every Kiro connection import. This gives each OmniRoute connection its own dedicated OIDC client registration. Because each client registration is independent, refreshing or re-authenticating one account does not affect any other account's refresh token.

The isolation applies to all three import methods:

Import method	Isolation status
AWS Builder ID / IDC device-code flow	Isolated since the device-code flow was introduced
Import Token (manual refresh token paste)	Isolated from v3.8.0
Google / GitHub social login	Isolated from v3.8.0
Auto-Import (kiro-cli SQLite)	Isolated from v3.8.0 (SQLite path was already isolated; SSO-cache fallback is now also isolated)

---

Migration Note for Connections Created Before v3.8.0

Connections imported before v3.8.0 do not have a dedicated OIDC client registration stored in providerSpecificData. These connections continue to work but use the shared social-auth refresh endpoint, which means two such connections can still invalidate each other.

To gain isolation: delete the old connection from Dashboard → Providers and re-import it using any of the supported import flows. All newly created connections will receive their own client registration automatically.

---

Adding Two Kiro Accounts Side by Side

Prerequisites

• OmniRoute v3.8.0 or later.
• A working Kiro account (email + password, Google, or GitHub login).
• Optionally a second Kiro account.

Step 1: Import the first account

1. Open Dashboard → Providers → Add Provider → Kiro.
2. Choose one of:
   • Import Token — paste a refresh token starting with aorAAAAAG.
   • Google / GitHub login — complete the OAuth flow in the browser.
   • Auto-Import — click the button; OmniRoute reads credentials from the local kiro-cli database or ~/.aws/sso/cache.
3. The connection is saved. OmniRoute automatically registers a dedicated OIDC client for it.

Step 2: Import the second account

Repeat step 1 for the second account. Because each import creates a separate OIDC client registration, the two connections are fully isolated.

Step 3: Verify both connections are active

1. Dashboard → Providers — both Kiro connections should show Active status.
2. Dashboard → Health — both connections should pass their token health check.

Step 4: Use a combo to route between accounts

Create a combo with both connections as targets to load-balance or fall back between them:

kiro/kiro-dev → kiro/kiro-pro

See FEATURES.md and the routing documentation for combo configuration.

---

Enterprise / IDC Users

For AWS IAM Identity Center (IDC) accounts, use the AWS Builder ID / IDC device-code flow from Dashboard → Providers → Kiro → Device Code. The device-code flow has always been fully isolated. No re-import is needed for these connections.

Enterprise users who operate in a non-default AWS region can specify the region when importing via the Import Token API:

curl -X POST http://localhost:20128/api/oauth/kiro/import \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "aorAAAAAG...", "region": "eu-west-1"}'

The region field defaults to us-east-1 when omitted.

---

OIDC Client Expiry

AWS SSO OIDC public clients typically expire after 90 days (clientSecretExpiresAt). OmniRoute stores this timestamp in providerSpecificData for observability. If a connection stops refreshing after ~90 days, re-import the connection to obtain a fresh OIDC client registration. Automatic re-registration on expiry is tracked as a future improvement.

---

Troubleshooting

Second account keeps getting logged out

• Check both connections in Dashboard → Providers and confirm each shows a non-null clientId in its raw JSON (visible via the info icon). If either connection is missing clientId, it was imported before v3.8.0 — re-import it.

Import fails with "Token validation failed"

• Ensure the refresh token starts with aorAAAAAG.
• Ensure OmniRoute can reach https://oidc.us-east-1.amazonaws.com (or the configured region). If you are behind a corporate proxy, set a provider-level proxy in Dashboard → Settings → Proxies.

For other issues, see the main TROUBLESHOOTING.md.