Connect to AWS

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, then go to the 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.

{
  "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:

npm install @trigger.dev/sdk@latest @aws-sdk/client-sts @aws-sdk/client-s3

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

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.

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

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

{
  "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"
        }
      }
    }
  ]
}

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

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.

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:

{
  "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 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 and replace its Condition with:

{
  "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:

{
  "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.

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Webhooks

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Configure AWS

Create an OIDC identity provider

Create an IAM role

Use the role in your task

Provider options

Session tags and task-level access

Restrict a role to one task

Use tags in resource permissions

Without the helper

Trust all Preview branches

​Configure AWS

​Create an OIDC identity provider

​Create an IAM role

​Use the role in your task

​Provider options

​Session tags and task-level access

​Restrict a role to one task

​Use tags in resource permissions

​Without the helper

​Trust all Preview branches

Configure AWS

Create an OIDC identity provider

Create an IAM role

Use the role in your task

Provider options

Session tags and task-level access

Restrict a role to one task

Use tags in resource permissions

Without the helper

Trust all Preview branches