This article discusses how to integrate the Amazon API Gateway with the Cequence platform using CloudFormation. You can also integrate using Terraform. This article is intended for AWS administrators who deploy and manage the integration across one or more accounts.

Integration architecture

The Amazon API Gateway integration for the Cequence platform is made of the following components.

Amazon API Gateway

Receives incoming requests from clients and routes the requests to the appropriate API backend services or applications.

Generates detailed log entries for each request and response, including headers, body, query parameters, and other metadata relevant to Cequence platform analysis.

Amazon CloudWatch

Receives log events from API Gateway and stores the log events in log groups.

Amazon CloudWatch limitations limit batch sizes to 1MB and 5000 transactions per second, per region. Use the Service Quotas service to change the transaction-per-second limit. The batch size limit cannot be increased. This link goes to an external site that may change over time.

Amazon EventBridge Scheduler

A serverless event management service that enables the triggering of an AWS service at a scheduled interval. Amazon EventBridge Scheduler triggers an AWS Lambda function that fetches API Gateway log events every minute.

AWS Lambda function

Triggered every minute by Amazon EventBridge Scheduler. Pulls the API Gateway log entries from AWS CloudWatch, transforms the entries into the payload format used by the Cequence platform, aggregates the entries over the last minute of activity, and posts the batch to the Cequence platform for analysis.

Before you start

Setting up the integration requires specific AWS access, Cequence credentials, and the integration bundle. Review the following requirements before you begin.

Required access and permissions

The integration requires the following access and permissions.

• An AWS account with sufficient permissions to deploy AWS CloudFormation StackSets and Lambda functions across multiple accounts and regions, across organizational units, or across the whole organization.
• Working REST or HTTP APIs deployed to various stages in API Gateway.
• Cequence Bridge release 5.6.2 or later.

To deploy across an organization, you need either a root account or a delegated StackSet administrator account. For details on delegated administration, see the AWS delegated administrator documentation. This link goes to an external site that may change over time. This deployment model is called service-managed. You can optionally filter a service-managed deployment to specific organizational units and accounts instead of the whole organization.

To deploy to multiple accounts without an organization-wide scope, establish trust relationships between accounts. For details, see the AWS self-managed permissions documentation. This link goes to an external site that may change over time. This deployment model is called self-managed. In the administrator account, create an IAM role named AWSCloudFormationStackSetAdministrationRole. In each target account, including the administrator account when you intend to deploy there, create an IAM role named AWSCloudFormationStackSetExecutionRole with an sts:AssumeRole trust relationship with the administrator account where StackSets are created.

Cequence credentials

The integration requires the following Cequence credentials.

• Client ID.
• Client secret.
• Auth endpoint.
• Bridge or Edge endpoint.

Creating a Cequence client ID and secret

Several Cequence components must authenticate to the Cequence platform in order to transmit and receive data. The following procedure creates the authentication credentials those components require.

1. Log in to the Cequence platform management portal. The URL for the management portal typically has the form https://ui.<your tenant name>.<domain>. Replace <your tenant name> with the name of your Cequence tenant organization. Replace <domain> with your domain name.
2. Navigate to General Settings > User Management.
   The User Management pane appears.
3. Select the Clients tab.
4. Select Add New Client.
   The new client dialog box appears.
5. In the Client Name field, type a name for the client.
   This name becomes the client ID. Note the client ID for later use.
6. Enable the Traffic Management toggle.
7. (Optional) To change the token lifespan from the default of 1800 seconds, type a whole number of seconds in Token Lifespan.
8. Select Save.
   A dialog box displaying the client secret appears.
9. Select the copy icon to copy the secret to the clipboard, then select Close.
   The client list appears.
10. Note the value of the client secret for later use. For security reasons, this value does not display again.

The Cequence client ID and secret are now ready for use in the environment variables file.

Items to download

Download the compressed archive file that contains the required files. After downloading, extract the compressed archive file.

tar -xvf cequence-aws-api-gateway*
cd cequence

Setting up the StackSet roles

Set up the following roles in your Amazon console before you deploy the integration.

Use the templates provided in the cequence/docs/stacksets-roles-templates directory of the extracted archive bundle file to create the roles. Do not use the default AWS templates.

• For StackSet administration, create an IAM role named AWSCloudFormationStackSetAdministrationRole in the administrator account. Configure the trust policy for the CloudFormation service and grant permissions to assume the execution role in the target accounts.
• In each target account, create a service role named AWSCloudFormationStackSetExecutionRole. Configure a trust policy to trust the administrator account. Log in as an administrator to each target AWS account and create the role using CloudFormation. Use cequence/docs/stacksets-roles-templates/AWSCloudFormationStackSetExecutionRole.yml as the template file. Use the AWS account ID of your StackSet administrator as the value of the AdministratorAccountIds parameter.

Required IAM role and permissions

The user account deploying the CloudFormation template and running the scripts to enable or disable the integration must have the following IAM role and permissions. Create an AWS policy with the following permissions. When you use a custom S3 bucket prefix, update the S3 resource ARNs in the policy to match that prefix.

Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ScanRegions",
            "Effect": "Allow",
            "Action": "ec2:DescribeRegions",
            "Resource": "*"
        },
        {
            "Sid": "IAMRoleManagement",
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:PassRole",
                "iam:DeleteRole",
                "iam:ListRoles",
                "iam:ListRolePolicies",
                "iam:PutRolePolicy",
                "iam:GetRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:ListInstanceProfilesForRole",
                "iam:UpdateAssumeRolePolicy",
                "sts:AssumeRole",
                "iam:TagRole",
                "iam:UntagRole"
            ],
            "Resource": "arn:aws:iam::*:role/*"
        },
        {
            "Sid": "IAMPolicyAccess",
            "Effect": "Allow",
            "Action": [
                "iam:GetPolicy",
                "iam:ListPolicyVersions"
            ],
            "Resource": "arn:aws:iam::aws:policy/*"
        },
        {
            "Sid": "ServiceLinkedRoleCreation",
            "Effect": "Allow",
            "Action": [
                "iam:CreateServiceLinkedRole"
            ],
            "Resource": [
                "arn:aws:iam::*:role/aws-service-role/apigateway.amazonaws.com/*",
                "arn:aws:iam::*:role/aws-service-role/lambda.amazonaws.com/*",
                "arn:aws:iam::*:role/aws-service-role/scheduler.amazonaws.com/*"
            ]
        },
        {
            "Sid": "LambdaListFunctions",
            "Effect": "Allow",
            "Action": [
                "lambda:ListFunctions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "LambdaFunctionManagement",
            "Effect": "Allow",
            "Action": [
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:GetFunction",
                "lambda:InvokeFunction",
                "lambda:UpdateFunctionConfiguration",
                "lambda:UpdateFunctionCode",
                "lambda:ListVersionsByFunction",
                "lambda:GetFunctionCodeSigningConfig",
                "lambda:TagResource",
                "lambda:UntagResource"
            ],
            "Resource": "arn:aws:lambda:*:*:function:*"
        },
        {
            "Sid": "CloudWatchEventsManagement",
            "Effect": "Allow",
            "Action": [
                "events:PutRule",
                "events:PutTargets",
                "events:DescribeRule",
                "events:ListTagsForResource",
                "events:DeleteRule"
            ],
            "Resource": "arn:aws:events:*:*:*"
        },
        {
            "Sid": "SchedulerManagement",
            "Effect": "Allow",
            "Action": [
                "scheduler:CreateSchedule",
                "scheduler:UpdateSchedule",
                "scheduler:DeleteSchedule",
                "scheduler:GetSchedule",
                "scheduler:ListSchedules",
                "scheduler:TagResource",
                "scheduler:UntagResource"
            ],
            "Resource": "arn:aws:scheduler:*:*:schedule/*/*"
        },
        {
            "Sid": "LogsAccess",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:DeleteLogGroup",
                "logs:PutRetentionPolicy",
                "logs:DescribeLogGroups",
                "logs:ListTagsForResource",
                "logs:CreateLogDelivery",
                "logs:PutResourcePolicy",
                "logs:UpdateLogDelivery",
                "logs:DeleteLogDelivery",
                "logs:DescribeResourcePolicies",
                "logs:GetLogDelivery",
                "logs:ListLogDeliveries",
                "logs:FilterLogEvents",
                "logs:Unmask",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:DescribeLogStreams",
                "logs:TagResource",
                "logs:UntagResource"
            ],
            "Resource": "*"
        },
        {
            "Sid": "APIGatewayAccess",
            "Effect": "Allow",
            "Action": [
                "apigateway:GET",
                "apigateway:POST",
                "apigateway:PUT",
                "apigateway:PATCH",
                "apigateway:DELETE"
            ],
            "Resource": "arn:aws:apigateway:*:*:*"
        },
        {
            "Sid": "S3AccessUpdateArnIfCustomBucketPrefix",
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketAcl",
                "s3:GetBucketCORS",
                "s3:GetBucketWebsite",
                "s3:GetAccelerateConfiguration",
                "s3:GetBucketRequestPayment",
                "s3:GetBucketLogging",
                "s3:GetLifecycleConfiguration",
                "s3:GetReplicationConfiguration",
                "s3:GetEncryptionConfiguration",
                "s3:GetInventoryConfiguration",
                "s3:GetBucketTagging",
                "s3:GetBucketPolicyStatus",
                "s3:GetBucketObjectLockConfiguration",
                "s3:GetBucketPublicAccessBlock",
                "s3:GetBucketOwnershipControls",
                "s3:CreateBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:PutBucketPolicy",
                "s3:GetBucketPolicy",
                "s3:DeleteBucketPolicy",
                "s3:DeleteBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:PutBucketVersioning",
                "s3:DeleteObjectVersion",
                "s3:ListBucketVersions"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_CUSTOM_BUCKET_PREFIX-*",
                "arn:aws:s3:::YOUR_CUSTOM_BUCKET_PREFIX-*/*",
                "arn:aws:s3:::cequence-aws-api-artifacts-*",
                "arn:aws:s3:::cequence-aws-api-artifacts-*/*"
            ]
        },
        {
            "Sid": "CloudFormation",
            "Effect": "Allow",
            "Action": [
                "cloudformation:*"
            ],
            "Resource": "arn:aws:cloudformation:*:*:*"
        },
        {
            "Sid": "OrganizationRead",
            "Effect": "Allow",
            "Action": [
                "organizations:DescribeOrganization",
                "organizations:ListDelegatedAdministrators"
            ],
            "Resource": "*"
        }
    ]
}

Setting up the integration

Using CloudFormation to integrate the Cequence platform with the AWS API Gateway takes place over several phases. You can deploy the integration through a script or through the AWS console. Start by setting up the environment variables file, which both deployment paths use.

Setting up the environment variables file

The environment variables file controls the deployment. The following procedure creates the file and describes the variables that affect CloudFormation deployments.

1. Extract the downloaded compressed archive file.

   tar -xvf cequence-aws-api-gateway.tar.gz
   cd cequence

2. Navigate to the scripts folder. Make a copy of the .env.example file named .env. When your deployment type requires organizational-unit or account targeting, also copy the corresponding example configuration files.

   cd config-examples
   cp .env.example ../scripts/.env
   
   # Optional depending on the deployment type set in .env
   cp org-units-config-example.csv ../scripts/org-units-config.csv
   cp accounts-config-example.csv ../scripts/accounts-config.csv
   cp lambda-vpc.example.json ../scripts/lambda-vpc.json

3. Edit the .env file in the scripts directory.

   Setup validates that the .env file exists, that at least one API type (REST or HTTP) is enabled, and that the AWS CLI is properly configured before it proceeds.

   # =============================================================================
   # 1. MANDATORY
   # =============================================================================
   cequence_is_auth_enabled=true
   cequence_client_id=your_client_id_here
   cequence_client_secret=your_client_secret_here
   cequence_auth_endpoint=https://example.cequence.ai/auth/realms/example/protocol/openid-connect/token
   cequence_edge_endpoint=https://edge.example.cequence.ai/api-transactions
   # cloudformation | terraform
   cequence_deployment_type=cloudformation
   cequence_rest_api_enabled=true
   cequence_http_api_enabled=true
   
   # =============================================================================
   # 2. REGIONS
   #     all  |  us-east-1,us-west-2  |  scripts/regions-config.csv
   # =============================================================================
   cequence_aws_regions=all
   
   # =============================================================================
   # 3. MONITORING (optional)
   # =============================================================================
   cequence_http_log_group_name=cequence-http-api-access-logs
   # true = API Gateway already has a CloudWatch Logs role attached (skip attach)
   cequence_apigw_cloudwatch_role_already_attached=false
   # false = keep existing HTTP DestinationArns; true = rewrite all to the Cequence log group
   cequence_http_overwrite_log_destinations=false
   cequence_log_retention_days=1
   cequence_sampling_enabled=false
   cequence_default_sampling_rate=1.0
   cequence_api_discovery_ttl_ms=300000
   # CloudWatch fetch window in milliseconds, passed through to the Lambda function
   cequence_log_fetch_interval_ms=60000
   cequence_log_fetch_limit=10000
   cequence_log_ingestion_buffer_ms=60000
   # Edge or Bridge HTTP connection pool size (default 5)
   cequence_connection_pool_size=5
   # Maximum POST body size per Edge request in bytes. Default 1000000. Lower this value if you see HTTP 413 errors.
   # cequence_max_message_size_bytes=1000000
   
   # =============================================================================
   # 4. MULTI-ACCOUNT AND ORGANIZATIONS (CloudFormation StackSet)
   #     Mode: single (both false) | accounts (multi=true) | organizations (organization=true)
   # =============================================================================
   cequence_is_multi_account_deployment=false
   cequence_is_aws_organization_deployment=false
   # Accounts (when multi_account=true):  111122223333,444455556666  |  scripts/accounts-config.csv
   # cequence_aws_account_ids=scripts/accounts-config.csv
   # Organizational units (when organization=true):  all  |  ou-xxx,ou-yyy  |  scripts/org-units-config.csv
   # cequence_aws_org_unit_ids=scripts/org-units-config.csv
   # Account filter within organizational units: NONE | INTERSECTION | DIFFERENCE
   cequence_cfn_account_filter_type=NONE
   
   # =============================================================================
   # 5. LAMBDA AND COLLECTOR RUNTIME
   # =============================================================================
   cequence_log_level=info
   cequence_local_log_mode=false
   cequence_auto_install_dependencies=true
   cequence_auto_uninstall_dependencies=false
   
   # =============================================================================
   # 6. CLOUDFORMATION STACKSET AND CONSOLE
   # =============================================================================
   cequence_cfn_stackset_name=cequence-aws-apigw-stackset
   # true = CLI creates the StackSet; false = upload the template to S3 for the console
   cequence_cfn_auto_deploy_stackset=true
   # Defaults to the first region in cequence_aws_regions
   # cequence_cfn_preferred_region=
   
   # =============================================================================
   # 7. OPTIONAL FILE CONFIGS (JSON)
   #     API allow list: cp api-config.example.json scripts/api-config.json
   # =============================================================================
   # cequence_lambda_vpc_config_path=scripts/lambda-vpc.json
   cequence_auto_discover_apis=true
   # When false, only the APIs listed in api-config.json are collected (REST and HTTP).
   # cequence_api_config_path=scripts/api-config.json

4. Modify the variables as needed. For example, set cequence_cfn_auto_deploy_stackset to control whether the script deploys the StackSet automatically. When the value is true, the script deploys everything, including the StackSet. When the value is false, the script stops after the S3 upload so that you can continue manually through the AWS console.

For CloudFormation deployment, verify that all accounts in scope have every region in scope enabled in AWS. When any region is disabled in any account in scope, the deployment fails. This requirement applies to all accounts in the organization or organizational units selected, even when you filter selected accounts. To enable disabled regions, see the AWS region management documentation. This link goes to an external site that may change over time.

The following output shows the error that a disabled region produces.

Operation f8398eed-cc7c-47a9-a8ed-e82421d1a23f FAILED.
{
    "StackSetOperation": {
        "OperationId": "f8398eed-cc7c-47a9-a8ed-e82421d1a23f",
        "Action": "CREATE",
        "Status": "FAILED",
        "StatusReason": "Account XXXXXXXX is not opted into the following regions: [ap-south-2]."
    }
}

Deploying through the script

The deployment script uploads the integration artifacts to S3 and, when configured to do so, creates the StackSet and deploys the stack instances. Use this path when you set cequence_cfn_auto_deploy_stackset to true.

1. Make all scripts executable and run the deployment script.

   chmod +x *.sh
   ./deploy.sh

   A successful run shows a deployment summary and completion status on the console.

   [SUCCESS] StackSet deployment complete.
   [SUCCESS] ──────────────────────────────────────────────────
   [SUCCESS] Deployment finished successfully.
   [SUCCESS] What was deployed:
   [SUCCESS]   Method:              cloudformation
   [SUCCESS]   Infrastructure:      CloudFormation StackSet 'cequence-aws-apigw-stackset'
   [SUCCESS]   Regions:             us-west-2,ap-south-1
   [SUCCESS] ──────────────────────────────────────────────────

2. Log in to the CloudFormation console and verify that the StackSet is created successfully. When you run in the root account or the delegated StackSet administrator account with organization deployment enabled, check the StackSet under the Service-managed section. When you deploy to a single account, or to multiple accounts with multi-account deployment enabled, check the StackSet under the Self-managed section.

After the deployment script finishes, the deployment is complete. The remaining sections describe the manual console path for deployments that set cequence_cfn_auto_deploy_stackset to false.

Uploading artifacts for a manual console deployment

When you set cequence_cfn_auto_deploy_stackset to false, the deployment script uploads the artifacts to S3 without creating the StackSet. A successful run shows output similar to the following.

[SUCCESS] CloudFormation artifacts uploaded.
[INFO] StackSet template URL:
[INFO]   https://cequence-aws-api-gateway-<account-id>-<region>.s3.<region>.amazonaws.com/cloudformation/template.yaml
[INFO] Lambda code parameters (Console / StackSet):
[INFO]   LambdaCodeS3BucketPrefix = cequence-aws-api-gateway-<account-id>
[INFO]   LambdaCodeS3Key          = lambda/cequence-lambda-<version>.zip
[INFO] Manual CloudFormation next steps:
[INFO]   1. AWS Console: navigate to CloudFormation, then StackSets, then Create StackSet.
[INFO]   2. Paste the Amazon S3 URL above as the template.
[INFO]   3. StackSet name: cequence-aws-apigw-stackset
[INFO]   4. Set the Lambda code parameters shown above.
[INFO]   5. Add the tags cequence-integration=true, cequence-created=true, cequence-deployment-type=cloudformation.
[INFO]   6. After all stack instances are CURRENT, enable HTTP API access logging:
[INFO]        ./enable-http-api-logging.sh cequence-aws-apigw-stackset

Extract the S3 template URL and the Lambda code parameters from the script output. Note these values for use in the following procedure. Enabling HTTP API access logging in the final step is mandatory.

Preparing the template and resources

After you have the S3 template URL, create the StackSet through the AWS CloudFormation console. The following procedure prepares the template and starts the StackSet definition wizard.

1. In the AWS CloudFormation console, select StackSets > Create StackSet.
2. From the Permissions section, choose exactly one option, either the IAM execution role name AWSCloudFormationStackSetAdministrationRole or the IAM admin role ARN.
3. From the Prepare template section, select Template is ready.
4. Provide the S3 location of the template YAML file from earlier in this procedure.
5. Select Next.
   The StackSet definition wizard advances to the next step.
6. Type a name for the StackSet, such as aws-cequence-apigw-integration.
7. Type a description for the StackSet. An example description is "This StackSet facilitates the deployment and creation of AWS artifacts that enable Cequence and AWS API Gateway integration across regions and accounts."
8. Specify values for the parameters added from your template, then select Next.
   The StackSet definition wizard advances to the next step.

Cequence API configuration parameters

The following table describes the Cequence API configuration parameters.

Lambda configuration parameters

The following table describes the Lambda configuration parameters.

Content type configuration (optional)

Optionally, configure regular expressions to define supported response content types or unsupported static file extensions. The following regular expression defines supported response content types.

^[ ]*application/xml[ ]*;?.*$|^[ ]*application/soap\+xml[ ]*;?.*$|^[ ]*text/xml[ ]*;?.*$|^[ ]*application/soap[ ]*;?.*$|^[ ]*application/json[ ]*;?.*$|^[ ]*application/x-www-form-urlencoded[ ]*;?.*$|^[ ]*text/html[ ]*;?.*$

The following regular expression defines unsupported static file extensions.

/\.(css|swf|bmp|bin|csv|oga|jsonld|eot|opus|mpkg|xul|tif|midi|ico|ics|html|jar|3g2|ogv|otf|zip|cda|ogx|rar|7z|tar|png|webp|webm|woff|pptx|mpeg|doc|odp|weba|odt|ods|aac|tiff|gif|vsd|js|mid|arc|avi|sh|epub|bz|jpeg|woff2|bz2|3gp|azw|htm|jpg|xlsx|rtf|svg|ttf|wav|docx|xhtml|mp4|mp3|txt|git|gz|pdf|ppt|abw|mjs|csh|php|xls|ts)$/i

Optional IAM role ARNs

The integration uses Amazon Resource Names (ARNs) with IAM roles. Optionally, specify the following ARNs.

• Cequence Lambda role ARN. Creates a new role when this value is not provided in the parameters.
• API Gateway CloudWatch role ARN. Creates a new role when this value is not provided in the parameters.
• EventBridge Scheduler role ARN. Creates a new role when this value is not provided in the parameters.

Configuring StackSet options

After you specify the parameters, configure the StackSet options. The following procedure sets tags, execution configuration, and required capabilities.

1. From the tags section, select Add new tag to add the following tags.

   cequence-integration: true
   cequence-created: true
   cequence-deployment-type: cloudformation

2. Set Execution Configuration to Active.
3. Select the checkboxes to acknowledge that AWS CloudFormation might create IAM resources with custom names and that AWS CloudFormation might require CAPABILITY_AUTO_EXPAND.
4. Select Next.
   The StackSet definition wizard advances to the next step.

Setting deployment options

The deployment options determine which accounts and regions receive the integration. The available targeting options depend on the permission model. A service-managed model can deploy to the entire organization or to selected organizational units. A self-managed model can deploy to specified accounts or to an organizational unit.

1. Select Deploy new stacks to add stacks to the StackSet.
2. Choose the deployment target for your permission model. For a self-managed deployment, choose Deploy stacks in accounts and provide target account IDs, or enter an organizational unit ID to deploy to all accounts in that unit. For a service-managed deployment, choose to deploy to the entire organization or to specific organizational units, with optional account filtering.
3. Choose a deployment region.
   • Choose Specific Regions and select target regions.
   • Alternately, choose All regions. Select only the enabled AWS regions. Disabling regions while All is selected causes a CloudFormation error.
4. Select Next.
   The StackSet definition wizard advances to the next step.
5. Set the value of Maximum concurrent accounts to the total number of accounts you want to deploy the template on.
6. Set the value of Failure tolerance to one less than the total number of accounts you want to deploy the template on.
7. Set Regional Concurrency to Parallel.
8. Set Concurrency mode to Soft failure tolerance.

Reviewing and deploying

The final phase reviews the configuration and submits the deployment.

1. Review all configurations.
2. Select Submit.
3. Monitor the deployment's progress. Look for a change in status from Running to Succeeded.

When the deployment succeeds, the integration is configured across the specified accounts and regions. You can check stack instances to verify that all stacks are successful.

Using an existing HTTP log stream

By default, the integration creates a new CloudWatch log stream for HTTP API access logs. When you want to use a log stream that already exists, follow the guidance below.

Before deployment, set the following variable in the .env file to the name of the existing log stream.

cequence_http_log_group_name=<existing log stream name>

You can update the log stream after deployment as follows.

1. Navigate to the Lambda function named cequence-api-gateway-lambda-<region>.
2. Select the Configuration tab, then select Environment variables.
3. Update the value of cequence_http_api_access_log_arn to the desired log stream.

Add the log stream ARN to the API logging configuration so that all logs are stored in the specified stream.

Enabling sampling

Sampling controls what proportion of traffic the Lambda function forwards to the Cequence platform. Configure sampling before deployment by setting the following variables in the .env file.

cequence_sampling_enabled=true
cequence_default_sampling_rate=0.5

When cequence_default_sampling_rate is set to 1.0, all traffic reaches the Cequence platform. When set to a lower value, such as 0.5, that percentage of traffic reaches the Cequence platform and the Lambda function drops the remainder.

Testing the integration

After deployment, verify that transactions flow to the Cequence platform. The following procedure generates traffic and checks the Lambda statistics.

1. Make API calls to your configured endpoints.
2. Wait one to two minutes for CloudWatch logs to populate.
3. Check the Lambda log group for statistics.
4. Select a log stream.
5. Expand the statistics entry.
   These statistics are visible only when cequence_log_level is set to debug.

The following example shows the Lambda statistics output.

{
    "timestamp": "2026-07-27T11:31:04.132Z",
    "level": "INFO",
    "requestId": "d06a6741-6ff7-49c7-a876-cfc29680237d",
    "message": {
        "collector_stats": {
            "general": {
                "plugin_version": "3.0.0",
                "region_name": "ap-south-1",
                "account_name": "<account-id>",
                "lambda_execution_time_ms": 2278,
                "local_log_mode": false
            },
            "cloudwatch_stats": {
                "cloudwatch_filter_start_time": "2026-07-27T11:29:00.000Z",
                "cloudwatch_filter_end_time": "2026-07-27T11:30:00.000Z",
                "total_cloudwatch_calls": 14,
                "total_cloudwatch_latency_ms": 1793,
                "cloudwatch_throttled_calls": 0,
                "cloudwatch_fetch_errors": 0,
                "total_log_groups_processed": 10,
                "failed_log_groups_processed": 0,
                "total_log_events": 51,
                "successful_converted_logs_to_transaction": 6,
                "failed_add_transactions_to_connector": 0
            },
            "api_stats": {
                "total_http_apis": 2,
                "total_rest_apis": 8,
                "total_http_apis_stages": 3,
                "total_rest_apis_stages": 9,
                "total_http_api_log_events": 2,
                "total_rest_api_log_events": 49,
                "incomplete_rest_api_streams": 2
            }
        },
        "connector_stats": {
            "general": {
                "open_connections": 10,
                "health_status": "healthy",
                "buffer_size": 0,
                "retry_attempts": 0,
                "circuit_breaker_status": "CLOSED"
            },
            "transactions": {
                "received": 6,
                "sent": 6,
                "in_queue_pending": 0,
                "dropped_total": 0,
                "dropped_by_sampling": 0
            }
        }
    }
}

The transactions appear on the Cequence platform Detection and Mitigation dashboard.

Adding more AWS regions for API discovery

AWS StackSets does not enable adding new regions to the same StackSet when you edit or override an existing CloudFormation template. The steps to add regions depend on how you deployed the integration.

When you deployed manually, delete the existing StackSet and create a new StackSet with the updated regions.

When you deployed through the script, follow these steps.

1. Set cequence_rest_api_enabled and cequence_http_api_enabled to false to disable the integration first.

2. Run the script with the destroy flag.

   ./destroy.sh --destroy

3. Re-enable cequence_rest_api_enabled and cequence_http_api_enabled in the .env file.
4. Update cequence_aws_regions in the .env file.

5. Run the deployment script again.

   ./deploy.sh

Disabling the integration

The steps to disable the integration depend on how you deployed the integration.

When you deployed through the script, edit the .env file. To disable one of REST or HTTP APIs, set that variable to false and run the deployment script again. To disable both, set both cequence_rest_api_enabled and cequence_http_api_enabled to false and run the script.

When you deployed manually through the AWS console, follow these steps.

1. Go to the CloudFormation console.
2. Select StackSets from the left navigation, then choose and select the StackSet.
3. Select Action and Override stackset parameters.
4. Provide the account number or the organizational units and select the regions where the integration needs to be disabled. Leave the defaults and select next.
5. Select CequenceHttpApiEnabled and CequenceRestApiEnabled from the list of parameters. Select Override stackset value.
6. Choose false and select Save Changes.
7. Verify that the new override value is updated.
8. Select Next.
9. Review the changes and select Submit.
10. Navigate to the Operations tab and verify that the operation has succeeded.

Updating the integration

The steps to update the integration depend on how you deployed the integration and on the kind of change. When you deployed through the script, edit the .env file and run the deployment script again. When you deployed manually, use the parameter override or template replacement procedures that follow.

Updating the parameters of the template

To update the parameters of the template, use the override action and update the values.

Updating the template to a new version

When you update to a new template version instead of updating parameter values, use the Replace option instead of the current template. Because AWS caches templates, replacement is necessary even when you use the same S3 link. AWS only fetches the template again upon replacement.

To update the template to a new version, re-run the environment setup procedure to upload the new template to the S3 bucket, then extract the S3 bucket URL. Navigate to the CloudFormation template, select the operations tab, use the edit action, and replace the YAML with the extracted S3 bucket link.

Update the StackSet under the following circumstances.

• Parameter changes.
• Adding or modifying resources.
• Template logic improvements.

Replace the StackSet by deleting the original StackSet and recreating a new StackSet under the following circumstances.

• The resource name changes.
• Fundamental architecture changes.
• Permission model changes.
• Cross-region dependency changes.
• Consistent update failures.
• Template structure overhaul.

Deleting the integration

Deleting the integration removes the StackSet definition and all associated stack instances. Delete the Cequence bundle from the S3 regional buckets through the script, then delete the StackSet through the AWS console.

Deleting the Cequence bundle from S3 regional buckets

Set the following variable in the .env file, then run the script with the destroy flag.

cequence_rest_api_enabled=false
cequence_http_api_enabled=false

./destroy.sh --destroy

When many regions are enabled, deleting the bundle can take some time.

Deleting the StackSet through the AWS console

You must delete all stack instances before deleting the StackSet. The following procedure deletes the stack instances and then the StackSet.

1. Go to the CloudFormation console.
2. Select StackSets from the left navigation.
3. Navigate to the Stack Instances tab, then select Actions > Delete Stacks From StackSet.
4. Provide the account numbers and select Add All Regions.
5. Select Next and Review.
6. Select Submit.
7. Navigate to the Operations tab and verify the status. Wait for the status to change to Succeeded. The change takes a few minutes depending on the number of accounts and regions enabled.
8. Select the StackSet.
9. Select Actions > Delete StackSet.
10. Confirm deletion.

The process removes the StackSet definition and all associated stack instances across the specified accounts and regions. The deletion is asynchronous. Verify that you have proper permissions, including the StackSet admin role, and consider the effect on resources managed by the StackSet instances before you proceed.

Known limitations of HTTP API logging

HTTP APIs have restricted logging capabilities compared to REST APIs. Details on HTTP API access log customization are available in Amazon's documentation. This link goes to an external site that may change over time.

The Cequence plugin does not capture HTTP API request and response headers or payload, due to AWS API Gateway limitations. The plugin adds the following placeholder values to HTTP API transactions instead.

Request Headers:
"cq-no-header: true"

Response Body:
{"cq-endpoints-only": "true"}

The following HTTP API log variables are available.

• requestTimeEpoch
• requestId
• accountId
• stage
• instance_id
• ip
• host
• http-version
• http-method
• uri-query-fragment
• status-code

Request and response body content is not logged for HTTP APIs. If your APIs already have access logs enabled in a format other than JSON, that format is not currently supported.

In case of problems

The following issues have known resolutions.

• Template caching. Use template replacement instead of update for version changes.
• Permission errors. Verify that all required IAM roles and policies are correctly configured.
• Deployment failures. Check CloudFormation stack events for detailed error messages.
• Lambda execution issues. Review Lambda function logs and increase the log level to debug when needed.
• Cross-region deployment issues. Verify that StackSet execution roles exist in all target regions.
• Failed region retries. When you retry a failed region, select all regions from the dropdown. Otherwise, the regions you leave unselected remain in a pending state.
• Role not visible in the role selection dropdown. Verify that the role's trust relationship allows the CloudFormation service to assume the role. Only a root account or delegated StackSet administrator account shows the Service-managed option.

Notes

The following notes describe body truncation behavior and log retention.

1. AWS API Gateway limits log events to 1024 bytes. Log events larger than 1024 bytes, such as request and response bodies, are truncated by API Gateway before submission to CloudWatch logs. This link goes to an external site that may change over time.

2. For REST APIs, the Cequence platform truncates request and response bodies larger than 32KB and adds the header cq-body-truncated: true. The truncated body content depends on the content type.

   Request Headers:
   "cq-no-header: true"
   
   Response Body:
   form: cq_body_truncated=true
   json: { "cq_body_truncated": "true" }
   xml: <cq_body_truncated>true</cq_body_truncated>
   soap: <soap:Envelope><soap:Body><cq_body_truncated>true</cq_body_truncated></soap:Body></soap:Envelope>
   html: <div>cq_body_truncated: true</div>

3. For HTTP APIs, request and response bodies are unavailable. The plugin sets the following response body and sends it to the Cequence platform.

   {"cq-endpoints-only": "true"}

4. Set the retention period for CloudWatch log groups associated with APIs deployed in AWS API Gateway to at least one day, or according to your retention policy.