> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Role Integration: Cross-Account IAM Role for Agents

> Connect agents to AWS through an IAM role that OneCLI assumes, with temporary credentials and per-agent permissions. No access keys shared.

## Overview

**AWS Role** connects agents to your AWS account without sharing access keys. You create an IAM role that trusts OneCLI, and OneCLI assumes it to get temporary credentials that expire after one hour. The gateway signs each request with SigV4, so your agent never sees any credentials.

For access keys instead, see [AWS](/docs/integrations/aws).

<a id="self-hosted" style={{ scrollMarginTop: "8rem" }} />

## Connect AWS Role

<Steps>
  <Step title="Copy the trust policy values">
    In the OneCLI dashboard, open **Connections** > **AWS Role** and click **Connect AWS Role**. Step 1 shows two values for your role's trust policy, each with a copy button:

    * **OneCLI Account ID:** the AWS account that assumes your role.
    * **External ID:** unique to your organization. It protects against the confused-deputy problem.

    <Frame caption="The AWS Role connect window in OneCLI.">
      <img src="https://mintcdn.com/chartdbinc/L4k9tYUENUtEpMY8/images/integrations/aws-role/onecli-connect-aws-role.png?fit=max&auto=format&n=L4k9tYUENUtEpMY8&q=85&s=4d5099643c4ea1fd90ab8f535085f7b1" alt="OneCLI connect window for AWS Role, showing step 1 with the OneCLI Account ID and External ID to copy, and the Role ARN and Default Region fields." width="1056" height="1914" data-path="images/integrations/aws-role/onecli-connect-aws-role.png" />
    </Frame>
  </Step>

  <Step title="Create the IAM role in AWS">
    In the AWS console, open **IAM** > **Roles** > **Create role**, choose **AWS account** > **Another AWS account**, paste the **OneCLI Account ID**, tick **Require external ID**, and paste the **External ID**. Attach the policies agents need, name the role `OneCLI`, and create it.

    For a full walkthrough with policy examples, see [Cross-Account Role](/docs/integrations/aws#cross-account-role-cloud) on the AWS page.
  </Step>

  <Step title="Finish in OneCLI">
    Back in the connect window, paste the role's **Role ARN** (for example `arn:aws:iam::123456789012:role/OneCLI`), choose the **Default Region**, and click **Connect AWS Role**.
  </Step>
</Steps>

<Note>
  The role's policies are the hard limit on what any agent can do. OneCLI can narrow that further per agent with session policies.
</Note>

## What agents can do

What agents can reach depends on the policies you attach to the role. OneCLI lets you grant these per agent:

| Area | What agents can do |
| - | - |
| **Read** | List S3 buckets and read objects, list and read Lambda functions, and access EC2, CloudWatch Logs, IAM, and STS |
| **Write** | Upload and delete S3 objects, invoke and delete Lambda functions, and access DynamoDB, SES, Secrets Manager, and CloudFormation |

## Controlling access

[Grant](/docs/guides/agent-access) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked. Put deletes and **Invoke Lambda function** behind approval. Organization [rules](/docs/guides/rules) add guardrails on top. A blocked request never reaches AWS.

To disconnect, remove the connection in **Connections** > **AWS Role**, then delete the role (or its trust policy) in IAM.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.