---
source_url: https://www.pubnub.com/docs/integrations/event-forwarding/create-s3-action
title: Create an S3 action
updated_at: 2026-09-30T07:20:08.000Z
---

# Create an S3 action

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Create an S3 action when you want [Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) to write matching PubNub events into an Amazon S3 bucket you control. You configure the action itself in the [Admin Portal](https://admin.pubnub.com/), but S3 requires an AWS bucket and an IAM role that trusts PubNub's AWS account before you can save it.

If you already have a bucket and an IAM role configured for PubNub, skip to [Configure the S3 action](#configure-the-s3-action).

## Create a bucket

1. Open the [Amazon S3 console](https://console.aws.amazon.com/s3/) and go to **Buckets**.
2. Click **Create bucket**, enter a name, and choose a region.
3. Configure any other bucket settings your organization requires.
4. Click **Create bucket**.
5. Note the bucket name and region. You need both to configure the action.

## Create an IAM role

Events & Actions writes to your bucket by assuming an IAM role that you create, so the role must trust PubNub's AWS account and grant write access to the bucket.

1. Open [AWS Identity and Access Management](https://console.aws.amazon.com/iam?p=iam&cp=bn&ad=c) and go to **Roles**.
2. Click **Create role** and name the role.
3. Select **AWS account** as the trusted entity type, choose **Another AWS account**, and enter `535363102202` as the account ID. This is PubNub's AWS account, and trusting it lets PubNub assume the role to write to your bucket.
4. Under **Options**, select **Require external ID**, then paste your app's subscribe key from the [keyset's page](https://www.pubnub.com/docs/architecture/authentication/set-up-your-account.md) in the Admin Portal into **External ID**. AWS recommends this option, and it stops anyone who learns the role ARN from assuming it without also knowing your subscribe key. Continue to the next step.

   The resulting trust policy looks like this:

   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "AWS": "arn:aws:iam::535363102202:root"
               },
               "Action": "sts:AssumeRole",
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "<your subscribe key>"
                   }
               }
           }
       ]
   }
   ```

5. Create a permissions policy that grants `s3:PutObject` on the objects in your bucket. Click **Create policy**, switch to the **JSON** tab, and paste the policy below. Replace `<bucket-name>` with your bucket's name.

   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": ["s3:PutObject"],
               "Effect": "Allow",
               "Resource": "arn:aws:s3:::<bucket-name>/*"
           }
       ]
   }
   ```

   The `Resource` must be an object ARN, which ends in `/*`. `s3:PutObject` applies to objects, so a policy that names only the bucket ARN (`arn:aws:s3:::<bucket-name>`) doesn't allow any upload, and the action fails to write. If you set an **Object key prefix** on the action, you can restrict the policy to that prefix, for example `arn:aws:s3:::<bucket-name>/pubnub-events/*`. If your organization adds bucket-level actions such as `s3:ListBucket`, put them in a separate statement whose `Resource` is the bucket ARN without `/*`.

   Use the [ARN reference guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) if you need help formatting the ARN.

6. Finish the policy wizard, attach the new policy to the role, and click **Next**.
7. Name the role and click **Create role**.
8. Note the role's ARN. You need it to configure the action.

Use Terraform instead of the console

Apply this equivalent [Terraform](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) configuration to create the same bucket, IAM role, and policy.

```hcl
resource "random_string" "random" {
  length  = 8
  upper   = false
  special = false
}
resource "aws_s3_bucket" "pubnub_s3" {
  bucket = "pubnub-s3-example-${random_string.random.result}"
  tags = {
    PubNub = "Example"
  }
}
data "aws_iam_policy_document" "pubnub_s3_role" {
  statement {
    actions = ["sts:AssumeRole"]
    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::535363102202:root"]
    }
    condition {
      test     = "StringLike"
      variable = "sts:ExternalId"
      values   = ["<your subscribe key>"]
    }
  }
}
resource "aws_iam_role" "pubnub_s3_example" {
  name               = "pubnub-s3-example"
  path               = "/"
  assume_role_policy = data.aws_iam_policy_document.pubnub_s3_role.json
}
resource "aws_iam_policy" "pubnub_s3_example" {
  name        = "pubnub-s3-example"
  path        = "/"
  description = "PubNub example S3 policy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action   = ["s3:PutObject"]
        Effect   = "Allow"
        Resource = "${aws_s3_bucket.pubnub_s3.arn}/*"
      },
    ]
  })
}
resource "aws_iam_role_policy_attachment" "pubnub_s3_attach" {
  role       = aws_iam_role.pubnub_s3_example.name
  policy_arn = aws_iam_policy.pubnub_s3_example.arn
}
```

show all
49
lines

## Configure the S3 action

1. In **Events & Actions** in the [Admin Portal](https://admin.pubnub.com/), select your app and keyset, then click **+ Add Action**.
2. Click **Amazon S3** to select the action type.
3. Paste the bucket name and role ARN you noted earlier into **Bucket Name** and **Role ARN**.
4. Choose the **Region** that matches your bucket.
5. If you want to organize objects like folders inside the bucket, add an **Object key prefix**.
6. If you expect a high volume of events, enable **Batching** to combine multiple events into a single upload instead of writing one object per event. See [Available actions](https://www.pubnub.com/docs/integrations/event-forwarding/available-actions.md) for the batch size and time bounds, and [Events & Actions quotas](https://www.pubnub.com/docs/pricing/quotas.md#events--actions) for the bounds on your tier. If you turn on batching, the object may not appear in the bucket until the batch's time bound elapses, so account for that delay when you test.
7. If you want failed uploads retried automatically, enable and configure **AWS S3 retry**. See [Available actions](https://www.pubnub.com/docs/integrations/event-forwarding/available-actions.md) for the retry policy and backoff formula.
8. Next to **Actions**, click **Add event listener** and pair the action with an existing event listener, or [create one](https://www.pubnub.com/docs/integrations/event-forwarding/configure.md).
9. Click **Save changes**.

An Events & Actions Amazon S3 batch larger than 5 MB uses an [Amazon S3 multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html), which splits the batch into parts automatically.

[Publish](https://www.pubnub.com/docs/pub-sub/publish/overview.md) a message that matches the paired listener's filter to confirm the action writes an object to your bucket.

You can export logs from your [Functions](https://www.pubnub.com/docs/message-processing/serverless/create-function.md) using an S3 action configured the same way.

## Related tasks

* [Configure Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/configure.md). Create the event listener that triggers this action.
* [Available actions](https://www.pubnub.com/docs/integrations/event-forwarding/available-actions.md). Look up the retry, envelope, and batching settings shared by every action type.
* [Create a Kafka action](https://www.pubnub.com/docs/integrations/event-forwarding/create-kafka-action.md). Forward matching events to an Apache Kafka topic instead of S3.
* [Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md). Understand event listeners, filters, and the concepts behind Events & Actions.

Last updated at: 2026-09-30T07:20:08.000Z