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

# IAM policies

> The AWS Identity and Access Management (IAM) roles and policies Operata's Amazon Connect integration requires — trust policies, attached policies, and the administrator policy for manual deployments outside AWS CloudFormation.

Operata's Amazon Connect integration uses two AWS Identity and Access Management (IAM) roles: the Amazon EventBridge Pipe execution role and the Lambda service role. The default AWS CloudFormation template creates and wires both. This page lists every trust policy, attached policy, and the administrator policy you need when deploying manually.

<Check>
  The default CloudFormation template creates and attaches every role
  and policy on this page. Read it only if you need to audit, modify, or
  deploy the integration manually outside CloudFormation.
</Check>

## Roles

| Role                            | Trust principal        | Attached policies                                                                              | Purpose                                                                                                                    |
| ------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| EventBridge Pipe execution role | `pipes.amazonaws.com`  | Kinesis source, Lambda invocation, API destination                                             | Reads Contact Trace Records (CTRs) from Kinesis, invokes the redactor Lambda, sends events to the Operata API destination. |
| Lambda service role             | `lambda.amazonaws.com` | `AWSLambdaBasicExecutionRole` (managed), Secrets Manager, EC2 ENI (VPC only), S3 (upsert only) | Runs the redactor Lambda, reads the Operata API token from Secrets Manager, and (optionally) reads agent data from S3.     |

## EventBridge Pipe execution role

### Trust policy

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pipes.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "{AWS Account ID}",
          "aws:SourceArn": "arn:aws:pipes:{AWS Region}:{AWS Account ID}:pipe/operataEventsPipe-{Instance Name}-amazonConnect"
        }
      }
    }
  ]
}
```

### Kinesis source policy

Reads Contact Trace Records (CTRs) from the Amazon Connect Kinesis stream.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:DescribeStream",
        "kinesis:DescribeStreamSummary",
        "kinesis:GetRecords",
        "kinesis:GetShardIterator",
        "kinesis:ListShards",
        "kinesis:ListStreams"
      ],
      "Resource": "{CTR Kinesis Stream ARN}"
    }
  ]
}
```

### Lambda invocation policy

Invokes the redactor Lambda for enrichment and redaction.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction",
        "lambda:InvokeFunctionUrl"
      ],
      "Resource": "arn:aws:lambda:{AWS Region}:{AWS Account ID}:function:CloudCollectorV3Stack-cloudcollectorv3redactor*"
    }
  ]
}
```

### API destination policy

Sends processed events to the Operata API destination. CloudFormation names the destination ARN `operataEndpointGroup-{Operata-Group-ID}`.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "events:InvokeApiDestination",
      "Resource": "{API Destination ARN}"
    }
  ]
}
```

## Lambda service role

### Trust policy

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

### Managed policy

Attach the AWS managed policy `AWSLambdaBasicExecutionRole`. It grants the Lambda permission to write to CloudWatch Logs.

### Secrets Manager access policy

Reads the Operata API token from Secrets Manager. The secret name
follows the pattern `cloud-collector-v3/ctr/{Operata Group ID}/apiToken`.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:{AWS Region}:{AWS Account ID}:secret:cloud-collector-v3/ctr/{Operata Group ID}/apiToken-*"
    }
  ]
}
```

### EC2 network interface policy

Required only when the Lambda runs in a VPC. Lets it create and manage
the network interfaces in the deployment subnets.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:AttachNetworkInterface",
        "ec2:CreateNetworkInterface",
        "ec2:DeleteNetworkInterface",
        "ec2:DescribeInstances",
        "ec2:DescribeNetworkInterfaces"
      ],
      "Resource": "*"
    }
  ]
}
```

### S3 access policy

Required only when CTR upsert is enabled. Lets the Lambda read agent
data files from your S3 bucket.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::{Agent Data Bucket Name}/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::{Agent Data Bucket Name}"
    }
  ]
}
```

## Administrator deployment policy

For manual installs outside CloudFormation, attach the following policy to your deploying principal. It covers the minimum permissions to create every resource the integration uses.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IAMRoleAndPolicyManagement",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:CreatePolicy",
        "iam:AttachRolePolicy",
        "iam:PutRolePolicy",
        "iam:GetRole",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "iam:ListRolePolicies",
        "iam:ListAttachedRolePolicies",
        "iam:PassRole",
        "iam:TagRole",
        "iam:UpdateAssumeRolePolicy"
      ],
      "Resource": [
        "arn:aws:iam::*:role/CloudCollectorV3Stack-*",
        "arn:aws:iam::*:role/operataEventBridgePipeRole*",
        "arn:aws:iam::*:policy/*-Operata-GroupId-*",
        "arn:aws:iam::*:policy/cloudcollectorv3*",
        "arn:aws:iam::*:policy/AgentDataS3Access"
      ]
    },
    {
      "Sid": "SecretsManagerManagement",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:PutSecretValue",
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret",
        "secretsmanager:TagResource"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:cloud-collector-v3/ctr/*/apiToken-*"
    },
    {
      "Sid": "EventBridgeManagement",
      "Effect": "Allow",
      "Action": [
        "events:CreateConnection",
        "events:CreateApiDestination",
        "events:UpdateConnection",
        "events:UpdateApiDestination",
        "events:DescribeConnection",
        "events:DescribeApiDestination",
        "events:ListConnections",
        "events:ListApiDestinations",
        "events:TagResource"
      ],
      "Resource": [
        "arn:aws:events:*:*:connection/operataAPIgroup-*",
        "arn:aws:events:*:*:destination/operataEndpointGroup-*"
      ]
    },
    {
      "Sid": "EventBridgePipeManagement",
      "Effect": "Allow",
      "Action": [
        "pipes:CreatePipe",
        "pipes:UpdatePipe",
        "pipes:StartPipe",
        "pipes:StopPipe",
        "pipes:DescribePipe",
        "pipes:ListPipes",
        "pipes:TagResource"
      ],
      "Resource": "arn:aws:pipes:*:*:pipe/operataEventsPipe-*"
    },
    {
      "Sid": "LambdaFunctionManagement",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionCode",
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:AddPermission",
        "lambda:RemovePermission",
        "lambda:TagResource",
        "lambda:ListVersionsByFunction"
      ],
      "Resource": "arn:aws:lambda:*:*:function:CloudCollectorV3Stack-cloudcollectorv3redactor*"
    },
    {
      "Sid": "LambdaS3CodeAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion"
      ],
      "Resource": "arn:aws:s3:::*-operata-shared-assets-prod/redactor-*.zip"
    },
    {
      "Sid": "KinesisReadAccess",
      "Effect": "Allow",
      "Action": [
        "kinesis:DescribeStream",
        "kinesis:ListStreams"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudFormationAccess",
      "Effect": "Allow",
      "Action": [
        "cloudformation:DescribeStacks",
        "cloudformation:ListStacks"
      ],
      "Resource": "*"
    }
  ]
}
```

## Manual deployment order

For manual installs, create resources in this order. Each step assumes you have attached the administrator policy above to your deploying principal.

1. Create the Secrets Manager secret
   `cloud-collector-v3/ctr/{Operata Group ID}/apiToken` with your
   Operata API token as the value.
2. Create the Lambda service role with the `lambda.amazonaws.com`
   trust policy. Attach `AWSLambdaBasicExecutionRole`, the Secrets
   Manager policy, the EC2 ENI policy (VPC only), and the S3 policy
   (upsert only).
3. Create the EventBridge Pipe execution role with the
   `pipes.amazonaws.com` trust policy. Attach the Kinesis source,
   Lambda invocation, and API destination policies.
4. Deploy the redactor Lambda. Name pattern
   `CloudCollectorV3Stack-cloudcollectorv3redactor-{unique-id}`,
   runtime `provided.al2`, handler `bootstrap`, timeout 60 seconds.
5. Create the EventBridge connection
   `operataAPIgroup-{Operata Group ID}` with `API_KEY` authentication
   and header `Operata-API-Key`.
6. Create the EventBridge API destination
   `operataEndpointGroup-{Operata Group ID}`. Endpoint
   `https://api.operata.io/v2/aws/events/contact-record`, method `POST`.
7. Create the EventBridge Pipe
   `operataEventsPipe-{Instance Name}-amazonConnect`. Source: the
   Kinesis CTR stream. Enrichment: the redactor Lambda. Target: the
   API destination. Filter: `{ "data": { "Channel": ["VOICE"] } }`.

Verify the pipe status is `RUNNING` and watch CloudWatch Logs for the
Lambda function. Place a test contact through Amazon Connect and
follow [Verify the integration](/docs/ctr-installation#verify) on the
installation guide.

## Common deployment errors

| Error                                             | When                                                                    | Recover                                                                                 |
| ------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `AccessDenied` on `iam:PassRole`                  | Deploying principal can't pass the EventBridge Pipe or Lambda roles.    | Attach `iam:PassRole` for both role ARNs to the deploying principal.                    |
| `InvalidParameterException` on `pipes:CreatePipe` | The Kinesis stream ARN is malformed or in another region.               | Verify the ARN matches the region you're deploying to.                                  |
| `ResourceNotFoundException`                       | A dependency was created out of order.                                  | Re-run in the order in [Manual deployment order](#manual-deployment-order).             |
| Lambda connection timeout                         | Lambda is in a VPC without route to Secrets Manager or the Operata API. | Add a VPC endpoint for Secrets Manager, or move the Lambda to a subnet with NAT egress. |

## Related

* [Concept: Cloud Collector](/docs/concepts-cloud-collector) — the data path these roles serve.
* [Install CTR collection](/docs/ctr-installation) — the default CloudFormation deploy.
* [KMS encryption](/docs/kms-encryption) — adds CMK access to the EventBridge Pipe role.
* [Troubleshoot the AWS integration](/docs/aws-troubleshooting) — covers Secrets Manager rotation and connection failures.