Bedrock IAM

IAM enables Claude Code, OpenCode, and Codex through a dedicated inference role. Kiro keeps its own API key. Platform administrators choose the mode in Admin → Agents → Platform Agent Credentials.

Configure a role

Complete the deployment prerequisites and manual setup first. Set AIDLC_ENVIRONMENT to your configured logical environment, not your AWS profile. It must match the environment value in your .tfvars file. The default configuration files are terraform/environments/<environment>.tfvars and terraform/environments/<environment>.s3.tfbackend; the setup guide documents overrides for files stored elsewhere.

: "${AIDLC_ENVIRONMENT:?Set AIDLC_ENVIRONMENT to your configured environment}"
./scripts/deploy-terraform.sh "$AIDLC_ENVIRONMENT" &&
  ./scripts/deploy-frontend.sh "$AIDLC_ENVIRONMENT"

Managed environments must run an image with IAM authentication support. Publish an updated environment where necessary. The runtime reports protocol 2, the keys and iam modes, and IAM connection verification; the control plane checks support before granting access, probing the selected runtime if its recorded qualification is missing or does not include the requested mode. Test connection reports that the environment must be republished when its runtime cannot verify IAM connections.

1. Select IAM, then Set up IAM connection (Change IAM connection once IAM is active).
2. Enter the inference account, region, role name or path, and optional ExternalId. The inference account and region can differ from the application, within the same AWS partition.
3. For a new role, run the generated CloudShell commands in their indicated accounts. For an existing role, select I already have an inference role, then Continue to connection test. This skips the AWS setup step. The trust policy names the credential broker; the broker policy allows assumption of that exact inference role.
4. Choose Test connection. This checks STS assumption and paginated Bedrock model discovery from the runtime. It does not invoke a model or prove model entitlements/Mantle access.
5. Choose Review connection change, check the proposed role and region and any work it says is affected, then Confirm change (Confirm anyway when started work is affected).
6. Select models available in the inference account and region. The policy supports Bedrock Runtime inference for Claude Code/OpenCode and Bedrock Mantle for Codex.

An existing role that passes the connection test can proceed directly to review. If the test fails, the wizard shows setup for connecting this deployment to the role. You can also open it with Connect this deployment to the role before testing. Required trust and permissions are available under a separate details panel for administrators.

CloudShell commands run in a separate Bash process with the AWS output pager disabled. On failure, the AWS error and failed step remain visible and your CloudShell session stays open. A downloaded script returns a nonzero status on failure. If creating a role reports EntityAlreadyExists, choose I already have an inference role or use a different role name. If role creation succeeded but adding permissions failed, use the existing-role permission help to finish setup; rerunning role creation will report that the role exists.

The application generates IAM setup documents; it does not modify AWS IAM itself. The broker needs STS access, and the runtime needs access to the broker and inference endpoints.

In Space Settings → Agent, platform administrators can Set space IAM role or Change space IAM role. Use platform connection reviews removal of the override. Space owners who are not platform administrators cannot configure, verify, or clear IAM roles. In IAM mode no agent credentials card offers a Bedrock key; Kiro remains independently configurable. Account Settings shows each person the platform default IAM role, region and status. It has no space context, so it notes that a space with its own role uses that role instead. A Bedrock key saved before the switch stays stored but unused, and it can only be cleared after the platform returns to Keys.

Switching back to Keys also requires review. Saved Bedrock keys become applicable again. An IAM role or mode change affects future selections; a started invocation retains its versioned connection.

Reuse a role across deployments

Two deployments can share one inference role. Each deployment has its own credential broker: the inference role must trust both brokers, and each broker needs permission to assume that role.

1. In the new deployment, select I already have an inference role and enter the existing role's account, name or path, inference region, and required ExternalId.
2. Continue to the connection test. If it already passes, proceed to review. Otherwise choose Connect this deployment to the role.
3. Copy or download the generated commands and run them in AWS CloudShell. When the inference role and application are in the same account, one script configures both sides. For different accounts, run the two scripts in their indicated accounts.
4. Choose Test connection again, then review and apply the connection change.

The reuse script reads the live trust policy and adds this deployment's broker statement, including its ExternalId if configured. It retains all existing statements, conditions and denies. It adds inference permissions under a policy name specific to this deployment and region, including the selected Mantle region, and leaves other policies intact. Repeating the same setup does not duplicate the trust statement. It does not create another role.

An assumption denial is reported as an IAM access error, including when credential preparation fails before the runtime's verification command starts. A model discovery denial is reported separately after credentials have been obtained. The connection check still does not test model invocation or Mantle access.

Renewal and expiry

The broker redeems a signed five-minute handoff grant, checks the pinned connection and execution, and assumes the exact role with an inference-only session policy. The resulting STS credentials last up to one hour. Renewal uses a separate signed audience bound to that connection, purpose, space and execution, with a fixed eight-hour deadline measured from the original grant. Renewal cannot switch roles, retrieve keys, or slide that deadline.

Each invocation's generic credential session owns an authenticated loopback AWS container-credential endpoint. Claude Code, OpenCode and Codex use their credential providers to acquire fresh credentials while the same process continues. STS credentials and renewal tokens stay in memory. Only the local endpoint and its random authorization token enter the trusted credential environment. The built-in MCP bridge retains application AWS identity in the runtime; it is not passed through the CLI.

Renewal starts five minutes before STS expiry. Transient failures retry every 30 seconds while credentials remain valid. Invalid grants, revoked connections and access denial stop renewal immediately. An independent timer cancels the invocation at STS expiry even if renewal hangs, or at the fixed eight-hour authorization limit. Cancellation force-stops the session's CLI process group, including tool descendants. The normal stage failure path reports credential unavailability and attempts its existing persistence/checkpoint work. There is no role fallback or automatic agent restart.

Detached work retains the same credential session until it finishes. A later invocation, including an answer to a parked conversation, redeems a fresh handoff grant and gets a fresh endpoint for the pinned connection. It does not reuse expired STS credentials or extend an earlier invocation's renewal token.

Revocation is checked against the stored connection on each redemption and renewal. AWS permissions and trust can also be revoked. Application selection changes do not revoke already-issued STS credentials; their AWS validity and the runtime's invocation cancellation remain distinct boundaries.

Foundation records

IAM uses non-secret, immutable connection revisions, policy records, space selections, impact reviews and audit records in the existing authentication control table. Reviewed activation writes the new connection and selection in one conditional transaction. Concurrent work or configuration changes invalidate stale reviews.

API keys retain their SSM SecureString paths. No configuration or run migration from the superseded IAM branch is provided. That branch's authType: iam, SSM mode settings and renewal protocol are not supported here.