> ## 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.

# Give Agents AWS Access With an IAM Role, Not Keys

> Connect agents to AWS through an IAM role that OneCLI assumes, with one-hour credentials, SigV4 signing at the gateway, and 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](https://onecli.sh/docs/integrations/aws.md).

## What you will set up

* An IAM role in your AWS account that trusts OneCLI with an External ID
* An AWS Role connection that assumes the role for temporary credentials
* Per-agent, per-tool access, with approval for deletes and Lambda invokes

## Connect AWS Role

**1. 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.

![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.](https://mintcdn.com/chartdbinc/L4k9tYUENUtEpMY8/images/integrations/aws-role/onecli-connect-aws-role.png?fit=max\&auto=format\&n=L4k9tYUENUtEpMY8\&q=85\&s=4d5099643c4ea1fd90ab8f535085f7b1)

The AWS Role connect window in OneCLI.

**2. 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](https://onecli.sh/docs/integrations/aws.md#cross-account-role-cloud) on the AWS page.

**3. 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**.

> [!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.

## 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](https://onecli.sh/docs/guides/agent-access.md) 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](https://onecli.sh/docs/guides/rules.md) 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.

## FAQ

> [accordion] Do I need to rotate keys with AWS Role?
>
> No. There are no long-lived keys. OneCLI assumes the role to get temporary credentials that expire after one hour.

> [accordion] Does the agent see any AWS credentials?
>
> No. The gateway signs each request with SigV4, so the agent never holds credentials. See [How it works](https://onecli.sh/docs/how-it-works.md).

> [accordion] What limits what an agent can do in AWS?
>
> The role's IAM policies are the hard limit. OneCLI can narrow that further per agent, and you choose per tool what runs freely or needs approval when you [grant](https://onecli.sh/docs/guides/agent-access.md) the connection.

> [accordion] What is the External ID for?
>
> It's unique to your organization and protects against the confused-deputy problem. Tick **Require external ID** when you create the role.


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