Step 1: Go to the IAM Console

1. Go to the AWS Console: https://console.aws.amazon.com/iam
2. In the left sidebar, click “Policies”
3. In the top-right corner, click the “Create policy” button

🔐 Step 2: Create a Custom S3 Access Policy

You’ll now define a policy to allow Coactive to read your dataset.

1. In the “Create Policy” screen:

• Click the “JSON” tab at the top

2. Add this statement with your given S3 Bucket name

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Action": ["s3:Get*", "s3:List*"],
7
      "Resource": [
8
        "arn:aws:s3:::<bucket-name>",
9
        "arn:aws:s3:::<bucket-name>/*"
10
      ]
11
    }
12
  ]
13
}

• Please replace <bucket-name> with your bucket name.
• arn:aws:s3:::<bucket-name> refers to the bucket itself — this allows Coactive to perform bucket-level operations such as listing objects (e.g., s3:ListBucket). This is required to view the contents or structure of the bucket during ingestion.
• arn:aws:s3:::<bucket-name>/* refers specifically to all objects inside the bucket You are also able to specify a prefix here with arn:aws:s3:::<bucket-name>/prefix/* . This grants Coactive permission to read the actual image and video files within that folder (e.g., s3:GetObject).

Together, these ensure that Coactive can:

1. See what objects exist in the dataset folder
2. Access and ingest the individual assets for processing

This approach adheres to AWS best practices by limiting access to only the necessary bucket and subfolder.

3. Click Next (bottom-right)

4. Add Policy Details

• Add a policy name: A clear and descriptive name indicating that this policy grants access to a specific S3 bucket, intended for Coactive’s ingestion process.
• Add a description (optional): Policy that allows Coactive to access images and videos in my S3 bucket.
• Click Create policy

• You’ll be returned to the “Policies” page. Your policy is now ready to attach to a role.

🛠️ Step 3: Create a New IAM Role

1. In the left sidebar, click “Roles”
2. In the top-right corner, click “Create role”

🧑‍🤝‍🧑 Step 4: Choose Trusted Entity

You’ll now define who can use (assume) this role.

1. Under “Trusted entity type”, select: AWS account

2. Under “An AWS account ID”, select Another AWS account and paste:

   863104360228

   (This is Coactive’s production AWS account)

3. Leave “Require external ID” unchecked

4. Click Next

   

📎 Step 5: Attach Your Custom S3 Access Policy

1. In the “Add permissions” screen:

   • Click the 🔄 refresh icon at the top-right of the list
   • In the search box, search for the policy name that you have just created

2. Check the box next to that policy to select it

3. Click Next (bottom-right)

   

🏷 Step 6: Name and Create the Role

1. In the “Role name” field, enter a role name:

2. (Optional) Description:

   IAM Role for Coactive to access my personal S3 demo dataset.

3. Click Create role

   

4. The role has now been created!

🔁 Step 7: Edit the Trust Relationship

Now you’ll tell AWS to trust only Coactive’s IAM role.

1. On the roles list page, click on the role name that you have created.
2. Click the “Trust relationships” tab
3. Click “Edit trust policy”
4. Replace the existing text with this:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Principal": {
7
        "AWS": "arn:aws:iam::863104360228:role/coactive-external-connections"
8
      },
9
      "Action": "sts:AssumeRole"
10
    }
11
  ]
12
}

Click “Update policy”

🔑 Step 8: Copy the Role ARN

You’ll need this to register the role with Coactive.

1. Still on the role details page, look for the “ARN” at the top
2. Copy it — it should look like this:

arn:aws:iam::<your-account-id>:role/<role-name>

Step 9: Use our Create Connection API to create the connection

Creat a new Connection using the Role ARN. Please use the API https://docs.coactive.ai/v-1/api-reference/api-reference/connections/create-connection and an example body is:

1
{
2
  "name": "<CONNECTION_NAME>",
3
  "config" : {
4
    "iam_role_arn" : "<ARN_FROM_STEP_8>",
5
    "bucket_name" : "<BUCKET_NAME>"
6
  },
7
  "test_location" : "s3://<BUCKET_NAME>/example_file.mp4",
8
  "type" : "aws_iam_role"
9
}

Step 10: Ingest Using the Connection Name

Using the connection name created in the previous step, start your ingestion!

1
import httpx
2
3
http = httpx.Client()
4
5
response = http.post(
6
    "https://api.coactive.ai/api/v1/ingestion/assets",
7
    headers={
8
        "authorization": "Bearer ACCESS_TOKEN"
9
    },
10
    json={
11
        "dataset_id": "YOUR_DATASET_ID",  # Replace this with your real dataset ID
12
        "connection_name": "<CONNECTION_NAME>",  # Key part here
13
        "assets": [
14
            {
15
                "source_path": "s3://bucket-name/10_images_10_videos/image1.jpg", # Replace this with your real source_path
16
                "metadata": {
17
                    "label": "example"
18
                }
19
            }
20
        ]
21
    }
22
)

Step 1: Copy the Coactive Bucket Policy Template

Replace all instances of YOUR_BUCKET_NAME with your actual bucket name:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Sid": "AllowCoactiveConnectionsListBucket",
6
      "Effect": "Allow",
7
      "Principal": {
8
        "AWS": "arn:aws:iam::863104360228:role/coactive-external-connections"
9
      },
10
      "Action": "s3:List*",
11
      "Resource": [
12
        "arn:aws:s3:::your-bucket-name"
13
      ]
14
    },
15
    {
16
      "Sid": "AllowCoactiveConnectionsReadObjects",
17
      "Effect": "Allow",
18
      "Principal": {
19
        "AWS": "arn:aws:iam::863104360228:role/coactive-external-connections"
20
      },
21
      "Action": "s3:Get*",
22
      "Resource": [
23
        "arn:aws:s3:::your-bucket-name/*"
24
      ]
25
    }
26
  ]
27
}

Step 2: Add the Policy to Your S3 Bucket

1. Go to the AWS Console: https://console.aws.amazon.com/s3
2. Click on your bucket
3. Go to the “Permissions” tab
4. Scroll down to “Bucket policy”
5. Click Edit
6. Paste the updated JSON into the editor
7. Click Save changes. Now Coactive’s role has read access to your bucket!

Step 3: Ingest Using the Fixed Connection Name "coactive"

You do not need to create a connection via API — just reference the special connection_name: "coactive" in your ingestion call.

Here’s a tailored example for you:

1
import httpx
2
3
http = httpx.Client()
4
5
response = http.post(
6
    "https://api.coactive.ai/api/v1/ingestion/assets",
7
    headers={
8
        "authorization": "Bearer ACCESS_TOKEN"
9
    },
10
    json={
11
        "dataset_id": "YOUR_DATASET_ID",  # Replace this with your real dataset ID
12
        "connection_name": "coactive",  # Key part here
13
        "assets": [
14
            {
15
                "source_path": "s3://bucket-name/10_images_10_videos/image1.jpg", # Replace this with your real source_path
16
                "metadata": {
17
                    "label": "example"
18
                }
19
            }
20
        ]
21
    }
22
)