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

# Configure AWS AssumeRole authentication

> Grant Baseten access to your AWS resources with an IAM trust policy

AWS AssumeRole lets Baseten pull private base images from Amazon ECR and
download model weights from Amazon S3 by assuming an IAM role in your AWS
account. You add a trust policy to an IAM role, and Baseten calls
`sts:AssumeRole` directly.

<Note>
  Baseten enables AWS AssumeRole by default for Enterprise organizations. On
  other plans, contact [Baseten support](mailto:support@baseten.co) or your
  Baseten representative to enable it.
</Note>

## How it works

1. Baseten uses a dedicated IAM role only to access customer AWS resources.
2. Baseten assigns your organization a unique, randomly generated [external
   ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html).
   After Baseten enables AWS AssumeRole for your organization, use
   [`truss whoami --show-aws-assume-role`](/reference/cli/truss/whoami#param-show-aws-assume-role).
   The command returns the external ID and the Baseten role ARN.
3. You create an IAM role in your AWS account with read access to your ECR
   repositories or S3 buckets, and a trust policy that allows Baseten's role
   to assume it and requires your external ID.
4. At build time, Baseten assumes your role with short-lived [AWS Security
   Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)
   credentials, presenting your organization's external ID, and pulls the image
   or mirrors the weights.

## Set up AWS AssumeRole

<Steps>
  <Step title="Get the Baseten role ARN and your external ID">
    Run `truss whoami --show-aws-assume-role` and copy both values:

    ```text AWS AssumeRole output theme={"system"}
    Baseten Role ARN: arn:aws:iam::<baseten-account-id>:role/baseten-customer-access
    AWS External ID: baseten-<32 hex characters>
    ```
  </Step>

  <Step title="Create an IAM role with a trust policy">
    Create an IAM role in your AWS account with this trust policy. Replace the
    placeholders with the Baseten role ARN and your external ID:

    ```json IAM trust policy theme={"system"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "<baseten-role-arn>"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<your-external-id>"
            }
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Attach permissions policies">
    Attach read-only policies for the resources your models need: ECR pull
    access for private base images or S3 read access for the buckets holding
    your model weights. For example:

    ```json ECR access (for base images) theme={"system"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "ecr:GetAuthorizationToken",
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "ecr:BatchCheckLayerAvailability",
            "ecr:GetDownloadUrlForLayer",
            "ecr:BatchGetImage"
          ],
          "Resource": "arn:aws:ecr:<region>:<aws-account-id>:repository/<repository-name>"
        }
      ]
    }
    ```

    Scope the pull actions to your repository. The
    `ecr:GetAuthorizationToken` action does not support resource-level
    permissions, so it keeps `"Resource": "*"`.

    ```json S3 access (for model weights) theme={"system"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": ["s3:GetObject", "s3:ListBucket"],
          "Resource": [
            "arn:aws:s3:::my-model-weights-bucket",
            "arn:aws:s3:::my-model-weights-bucket/*"
          ]
        }
      ]
    }
    ```
  </Step>

  <Step title="Reference the role in your Truss configuration">
    Configure `auth_method: AWS_ASSUME_ROLE` with your role's ARN and its region
    in `config.yaml`. See [Private registries
    (ECR)](/development/model/dependencies#aws-assumerole) for base images and
    [AWS S3 weights authentication](/development/model/bdn#aws-assumerole) for
    model weights.
  </Step>
</Steps>

## Limitations

* **AWS to AWS only.** Use AssumeRole only for AWS resources. For Google Cloud
  resources, use [GCP OIDC](/organization/oidc).
* **Build-time access only.** AWS AssumeRole covers pulling base images from
  ECR and mirroring model weights from S3. For your model code calling AWS
  services at inference time, use
  [OIDC at request time](/organization/oidc#use-oidc-at-request-time).
* **Organization-wide scoping.** The trust policy grants access for your whole
  Baseten organization. Baseten presents the same external ID for every model
  in it.

## Troubleshooting

### Audit role assumptions in CloudTrail

CloudTrail records role assumptions as `AssumeRole` events from the Baseten
role. Baseten prefixes session names with `baseten-model-build-`. Use these
events to verify when and how often Baseten accesses your resources.

### Common errors

| Error                                                                  | Likely cause                                                   | Solution                                                                                                                            |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Not authorized to perform sts:AssumeRole`                             | Trust policy principal or external ID doesn't match            | Verify the Baseten role ARN and that the `sts:ExternalId` condition uses the external ID from `truss whoami --show-aws-assume-role` |
| `The AWS_ASSUME_ROLE auth method is not enabled for this organization` | Baseten hasn't enabled AWS AssumeRole for your organization    | Contact [Baseten support](mailto:support@baseten.co) to enable it                                                                   |
| `Access Denied` after successful role assumption                       | Missing permissions on the role                                | Add the required ECR or S3 read permissions to the role's policies                                                                  |
| Region mismatch validation error on deploy                             | `aws_assume_role_region` doesn't match the ECR registry region | Set `aws_assume_role_region` to the region in your registry hostname                                                                |