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

# Use AWS From AI Agents Without Exposing Keys

> Let agents call S3, Lambda, EC2, and other AWS APIs while the gateway signs requests with SigV4. Use IAM access keys or a cross-account role.

## Overview

Buckle connects AI agents to AWS services (S3, EC2, Lambda, DynamoDB, and all other AWS APIs) through the gateway. The gateway handles SigV4 request signing, so agents make standard HTTP requests and credentials are injected transparently.

Buckle supports two connection methods for AWS:

| Method | Plan | Credentials | Best for |
| - | - | - | - |
| **Access Keys** | Free | Long-lived IAM access keys | Personal use, quick setup |
| **Cross-Account Role** | Cloud | Temporary STS credentials (1hr TTL) | Teams, B2B, production |

## What you will set up

* An AWS connection with IAM access keys or a cross-account role
* Automatic SigV4 signing on requests to `*.amazonaws.com`
* Per-action permissions and organization rules for AWS calls

## How the gateway handles AWS requests

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Gateway as Buckle Gateway
    participant STS as AWS STS
    participant AWS as AWS Service

    Agent->>Gateway: HTTP request to *.amazonaws.com
    alt Access Keys
        Gateway->>Gateway: Sign request with SigV4 using stored keys
    else Cross-Account Role
        Gateway->>STS: AssumeRole (Role ARN + External ID)
        STS-->>Gateway: Temporary credentials (1hr TTL)
        Gateway->>Gateway: Sign request with SigV4 using temp credentials
    end
    Gateway->>AWS: Signed request
    AWS-->>Gateway: Response
    Gateway-->>Agent: Response (credentials never exposed)
```

## Quick example

An agent calling S3 through the gateway, with no AWS SDK or credentials needed:

```bash theme={null}
# List buckets - the gateway injects SigV4 signing automatically
curl -s "https://s3.us-east-1.amazonaws.com/" | head -20

# Get an object from a specific bucket
curl -s "https://s3.us-east-1.amazonaws.com/my-bucket/data.json"

# Put an object (if the connection has write permissions)
curl -s -X PUT "https://s3.us-east-1.amazonaws.com/my-bucket/output.json" \
  -H "Content-Type: application/json" \
  -d '{"result": "processed"}'
```

The agent doesn't import `boto3`, configure `~/.aws/credentials`, or set environment variables. It makes a plain HTTP request and the gateway handles authentication.

## Access Keys (Free)

The simplest way to connect. You create an IAM user in AWS, generate access keys, and paste them into Buckle.

### Setup

**1. Create an IAM user in AWS**

Go to **IAM** > **Users** > **Create user**. Attach the permissions your agents need (e.g., `AmazonS3ReadOnlyAccess`).

**2. Generate access keys**

In the user's **Security credentials** tab, click **Create access key**. Select **Third-party service** as the use case. Copy the Access Key ID and Secret Access Key.

**3. Connect in Buckle**

Open the Buckle dashboard, go to **Settings** > **Apps** > **AWS**, and paste:

* **Access Key ID**: your `AKIA...` value
* **Secret Access Key**: the secret
* **Default Region**: the AWS region to use (e.g., `us-east-1`)

![Buckle connect window for AWS, showing the setup guide link and the fields to fill in.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/aws/buckle-connect-aws.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=184a1b1c8a9a38ad590e786f2c068cde)

The AWS connect window in Buckle.

> [accordion] More about access keys: how it works, use cases, limitations
>
> **How it works**
>
> 1. Credentials are encrypted and stored by Buckle
> 2. When an agent sends a request to `*.amazonaws.com`, the gateway intercepts it
> 3. The gateway signs the request using [AWS SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) with the stored credentials
> 4. The signed request is forwarded to AWS
>
> **Use cases**
>
> * Running `aws s3 ls` through a coding agent
> * Agents deploying Lambda functions or managing CloudFormation stacks
> * Querying DynamoDB or reading from S3 during code generation
>
> **Limitations**
>
> * Credentials are long-lived and don't expire until manually rotated
> * All agents with access to the connection share the same IAM permissions
> * You can restrict access at the gateway level with [rules](/docs/guides/rules.md) (block specific hosts/paths), but not at the AWS IAM level per agent

## Cross-Account Role (Cloud)

For teams and B2B deployments. Instead of sharing access keys, your AWS admin creates an IAM role in your account and grants Buckle permission to assume it. Buckle gets temporary credentials that expire after 1 hour and are automatically refreshed.

### Why use cross-account roles

* Buckle never stores your long-lived AWS credentials. The IAM role trust policy is the only configuration on your side.
* STS AssumeRole returns credentials that expire in 1 hour. If they leak, exposure is limited.
* The IAM role's policies define the maximum actions any agent can perform. You manage this in your own AWS account.
* Buckle can pass session policies per agent, further restricting what each agent can do within the role's permissions.

### Setup

**1. Get your External ID**

Open the Buckle dashboard, go to **Settings** > **Apps** > **AWS (Cross-Account)**. You'll see two values:

* **Buckle Account ID**: the AWS account that will assume the role
* **External ID**: a unique identifier for your organization (auto-generated)

Copy both values.

**2. Create an IAM role in your AWS account**

In the AWS console, go to **IAM** > **Roles** > **Create role**:

1. Select **Another AWS account**
2. Enter the **Buckle Account ID**
3. Check **Require external ID** and paste your **External ID**
4. Do **not** check "Require MFA" (Buckle is a machine identity)
5. Click **Next**

Attach the IAM policies that define what your agents can do. For example:

* `AmazonS3ReadOnlyAccess` for read-only S3 access
* A custom policy allowing specific actions on specific resources

Name the role (e.g., `Buckle-Agent-Role`) and create it.

**3. Connect in Buckle**

Copy the **Role ARN** from the role summary page (e.g., `arn:aws:iam::123456789012:role/Buckle-Agent-Role`).

Back in the Buckle dashboard, paste:

* **Role ARN**: the ARN you just copied
* **Default Region**: the AWS region to use

> [accordion] More about cross-account roles: how it works, permission model, examples
>
> **How it works**
>
> 1. When an agent sends a request to `*.amazonaws.com`, the gateway intercepts it
> 2. The gateway calls [STS AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) using Buckle's own AWS identity, with your role ARN and External ID
> 3. AWS returns temporary credentials (access key, secret key, session token) valid for 1 hour
> 4. The gateway caches these credentials and signs the request using SigV4
> 5. The signed request is forwarded to AWS
> 6. When the cached credentials near expiry, the gateway calls AssumeRole again automatically
>
> **The permission model**
>
> Cross-account roles give you two layers of permission control:
>
> ```
> IAM Role Policies (set by your AWS admin)
>     |
>     |  intersection (can only narrow)
>     v
> Session Policies (set per agent in Buckle)
> ```
>
> **IAM role policies** define the ceiling. Your AWS admin attaches policies to the role that determine the maximum permissions any agent can have. This is managed entirely in your AWS account.
>
> **Session policies** (optional) let Buckle administrators further restrict individual agents. For example, a role might allow `s3:*`, but a specific agent's session policy narrows it to `s3:GetObject` only. Session policies can only remove permissions, never add them.
>
> **Example: read-only vs full-access agents**
>
> Your AWS admin creates a role with `AmazonS3FullAccess`. In Buckle, you configure:
>
> | Agent | Session policy | Effective permissions |
> | - | - | - |
> | `deploy-agent` | None (uses full role) | `s3:*` |
> | `audit-agent` | `{"Statement":[{"Effect":"Allow","Action":"s3:GetObject","Resource":"*"}]}` | `s3:GetObject` only |
>
> The audit agent cannot write to S3 even if it tries, because the session policy restricts it at the AWS level.
>
> **Use cases**
>
> * B2B customers giving agents access to their AWS account with controlled permissions
> * CI/CD agents that need temporary AWS access for deployments
> * Multi-team environments where different agents need different permission levels
> * Compliance-sensitive workloads where long-lived credentials are not acceptable

## Comparison

| | Access Keys | Cross-Account Role |
| - | - | - |
| **Plan** | Free | Cloud |
| **Credential type** | Long-lived access keys | Temporary (1hr, auto-refreshed) |
| **Setup complexity** | Low (paste keys) | Medium (create IAM role + trust policy) |
| **Security** | Keys valid until manually rotated | Credentials expire automatically |
| **Who holds keys** | Buckle stores your access keys | Buckle only holds temporary tokens |
| **Permission control** | Gateway rules (host/path blocking) | IAM policies + per-agent session policies |
| **Per-agent scoping** | Same credentials for all agents | Different session policies per agent |
| **Key rotation** | Manual | Automatic (STS handles it) |
| **Best for** | Personal projects, quick testing | Production, teams, B2B |

## Per-action permissions

Once connected, the dashboard shows a permissions panel where you control exactly what agents can do with AWS. Each action has three modes:

| Mode | Icon | Behavior |
| - | - | - |
| **Allow** | Green | Agent can perform this action automatically |
| **Ask** | Yellow | Gateway pauses and requests human approval before proceeding |
| **Block** | Red | Request is rejected. Credentials are never injected. |

Buckle ships with preset permission groups:

* **Read-only**: allows listing and reading resources (S3 buckets, Lambda functions) while blocking writes and destructive operations
* **Custom**: configure each action individually

Available actions include:

* **List S3 buckets** / **Read S3 objects**: browse and read from S3
* **List Lambda functions** / **Get Lambda function**: inspect serverless functions
* **Access EC2**: manage compute instances
* **Access CloudWatch Logs**: read monitoring and log data

Permissions apply to all connected accounts for this integration. For per-agent scoping, set each agent's [grant](/docs/guides/agent-access.md) on the connection.

## Controlling access

Both connection methods are per agent: [grant](/docs/guides/agent-access.md) the connection to each agent that should use AWS. Organization [rules](/docs/guides/rules.md) then add guardrails that apply to everyone:

* Block requests to `iam.amazonaws.com` to prevent privilege escalation
* Limit S3 write operations to 100/hour
* Flag destructive operations (e.g., `DELETE` requests) for manual approval

Everything is checked before credential injection, so a blocked request never touches your secrets or reaches AWS.

## FAQ

> [accordion] How do I rotate AWS access keys?
>
> Create a new access key for the IAM user, then update it in **Settings** > **Apps** > **AWS**. Agents pick up the new key automatically. Then deactivate the old key in IAM. A cross-account role avoids long-lived keys entirely.

> [accordion] How do I keep AWS keys out of the agent's context?
>
> Don't configure `~/.aws/credentials` or environment variables in the agent. Store the keys in Buckle, and the gateway signs each request at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] Should I use access keys or a cross-account role?
>
> Access keys are the quick option for personal use. A cross-account role uses temporary credentials with a one-hour TTL and suits teams and production. See [Comparison](#comparison).

> [accordion] Can I require approval for destructive AWS calls?
>
> Yes. Use [per-action permissions](#per-action-permissions) when you [grant](/docs/guides/agent-access.md) the connection, or [rules](/docs/guides/rules.md) to flag `DELETE` requests for approval.


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