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

# Connect to AWS

> Assume an IAM role from your tasks without storing AWS access keys.

Use `awsCredentialProvider` to exchange a Trigger.dev OIDC token for temporary AWS credentials through STS. Pass it to your AWS SDK client to obtain and refresh credentials automatically.

Follow the [OIDC prerequisites](https://trigger.dev/docs/oidc.md#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.

## Configure AWS

### Create an OIDC identity provider

In AWS IAM, add an OpenID Connect identity provider with:

* **Provider URL**: your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`.
* **Audience**: `sts.amazonaws.com`, the audience used by the SDK's AWS helper.

Reuse the provider if one already exists for this issuer in your AWS account.

### Create an IAM role

Create a role with this trust policy. Replace the AWS account ID and organization slug, and replace `YOUR_ENVIRONMENT_SUBJECT` with the **complete subject copied from the dashboard**.

```json theme={"theme":"css-variables"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.trigger.dev/YOUR_ORG_SLUG"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
          "oidc.trigger.dev/YOUR_ORG_SLUG:sub": "YOUR_ENVIRONMENT_SUBJECT"
        }
      }
    }
  ]
}
```

Attach a permissions policy for the operations your task needs. For the S3 example below, allow `s3:GetObject` on `arn:aws:s3:::YOUR_BUCKET/trigger/*`. The trust policy controls who can assume the role; it does not grant S3 permissions. No session tags are required.

## Use the role in your task

Install the STS peer dependency and the AWS clients your task uses:

```bash theme={"theme":"css-variables"}
npm install @trigger.dev/sdk@latest @aws-sdk/client-sts @aws-sdk/client-s3
```

Replace the role ARN, region, bucket, and object key:

```typescript theme={"theme":"css-variables"}
import { task } from "@trigger.dev/sdk";
import { awsCredentialProvider } from "@trigger.dev/sdk/oidc/aws";
import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";

export const readFromS3 = task({
  id: "read-from-s3",
  run: async () => {
    const s3 = new S3Client({
      region: "us-east-1",
      credentials: awsCredentialProvider({
        roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
        region: "us-east-1",
      }),
    });

    const result = await s3.send(
      new GetObjectCommand({
        Bucket: "YOUR_BUCKET",
        Key: "trigger/example.txt",
      }),
    );
    return { contents: await result.Body?.transformToString() };
  },
});
```

Redeploy with CLI 4.8.3 or later and start a new run on that deployment.

> [!WARNING]
>
> Create the AWS client inside `run` and reuse it only within that run. A
> module-scope client can reuse a previous run's cached credentials and
> attribute AWS activity to that run.

### Provider options

| Option | Required | Behavior |
| - | - | - |
| `roleArn` | Yes | IAM role to assume. |
| `region` | Yes | Region for STS. The AWS service client's region does not configure STS. |
| `roleSessionName` | No | Defaults to the current run ID, sanitized to AWS's allowed characters and limited to 64 characters. |
| `durationSeconds` | No | Defaults to 3,600 seconds (one hour), subject to the role's allowed session duration. |
| `sessionTags` | No | Defaults to `false`. Set to `true` to include verified identity tags. Requires `sts:TagSession` in the role trust policy. |

For local development, use your own AWS credential chain, such as an AWS SSO profile. If a task runs both locally and deployed, select local credentials explicitly when `ctx.environment.type === "DEVELOPMENT"`.

## Session tags and task-level access

By default, a role's trust policy only checks the environment subject, so **every task in that environment** can assume the role. Session tags let you restrict a role to specific tasks, or scope resource permissions by task. They are off by default; existing roles keep working unchanged.

Trigger.dev adds these tags to the signed token. Values come from the verified run, never from payloads or caller input:

| Tag | Value |
| - | - |
| `TriggerOrganizationId` | Organization ID |
| `TriggerProjectRef` | Project reference, such as `proj_...` |
| `TriggerEnvironmentId` | Environment ID |
| `TriggerEnvironmentType` | `PRODUCTION`, `STAGING`, or `PREVIEW` |
| `TriggerTaskId` | Task identifier, such as `read-from-s3` |

These are AWS session tags, not Trigger.dev run tags. They are not transitive across role chaining.

### Restrict a role to one task

1. Update the trust policy. Add `sts:TagSession` to `Action` and a `TriggerTaskId` condition. AWS rejects tagged tokens if `sts:TagSession` is missing.

```json theme={"theme":"css-variables"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.trigger.dev/YOUR_ORG_SLUG"
      },
      "Action": ["sts:AssumeRoleWithWebIdentity", "sts:TagSession"],
      "Condition": {
        "StringEquals": {
          "oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
          "oidc.trigger.dev/YOUR_ORG_SLUG:sub": "YOUR_ENVIRONMENT_SUBJECT",
          "aws:RequestTag/TriggerTaskId": "read-from-s3"
        }
      }
    }
  ]
}
```

2. Enable tags in the task with `@trigger.dev/sdk` 4.8.4 or later, then redeploy:

```typescript theme={"theme":"css-variables"}
awsCredentialProvider({
  roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
  region: "us-east-1",
  sessionTags: true,
});
```

Older SDKs reject `sessionTags` in TypeScript and silently ignore it in JavaScript, which sends untagged tokens that this policy rejects.

> [!WARNING]
>
> Don't keep another statement that allows untagged assumption for the same subject, or any
> task can bypass the restriction. This protects against other tasks in the environment, not
> against people who can deploy: anyone who can deploy to the environment can deploy a task
> with the trusted ID.

To use tags only in permissions (below) without restricting tasks, add `sts:TagSession` to `Action` and omit the `aws:RequestTag` condition.

### Use tags in resource permissions

Tags are available in the role's permissions as `aws:PrincipalTag/...`. For example, one role can give each task its own S3 prefix:

```json theme={"theme":"css-variables"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::YOUR_BUCKET/${aws:PrincipalTag/TriggerTaskId}/*"
    }
  ]
}
```

### Without the helper

Request tags with `auth.getOIDCToken({ audience: "sts.amazonaws.com", awsSessionTags: true })`. Other audiences are rejected. Task IDs are sent unchanged, so a task ID that exceeds [AWS session tag limits](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) makes the STS call fail.

## Trust all Preview branches

For a single Preview environment, use its exact subject. To allow **any task** across **all current and future Preview branches** in one project, start with the basic trust policy in [Create an IAM role](#create-an-iam-role) and replace its `Condition` with:

```json theme={"theme":"css-variables"}
{
  "StringEquals": {
    "oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "oidc.trigger.dev/YOUR_ORG_SLUG:sub": "org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:PREVIEW:*"
  }
}
```

For a task-restricted Preview role, keep `sts:TagSession` in `Action` and add the task condition to `StringEquals`:

```json theme={"theme":"css-variables"}
{
  "StringEquals": {
    "oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
    "aws:RequestTag/TriggerTaskId": "read-from-s3"
  },
  "StringLike": {
    "oidc.trigger.dev/YOUR_ORG_SLUG:sub": "org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:PREVIEW:*"
  }
}
```

Keep the organization ID, project reference, `PREVIEW` environment type, and audience fixed. This deliberately grants access to anyone allowed to deploy a Preview branch in that project. Never wildcard the organization or project, or use this policy for a role intended only for Production or Staging.


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