View all connectors

Amazon Kiro

By integrating Amazon Kiro with DX, you can analyze daily Kiro usage metrics across IDE/CLI/plugin usage, overage behavior, and model-level message activity. Please refer to the API documentation below and our schema explorer to see what data DX imports.

Prerequisites

To connect Amazon Kiro to DX, you need:

  • An AWS account with Amazon Kiro usage report access
  • Access to AWS IAM to create a Policy and Role
  • An S3 bucket configured for Kiro report exports
  • A manually created user mapping CSV file uploaded to your S3 bucket (to map AWS user UUIDs to corporate email addresses)

Setup instructions

Amazon Kiro connections use IAM role-based authentication for secure cross-account access.

Step 1 - Get your External ID from DX

  1. In DX, navigate to Settings > Data connectors > Add connector > Amazon Kiro
  2. Copy the External ID displayed in the connection form

Step 2 - Create an IAM policy for S3 access

In your AWS account, create a custom IAM policy with S3 read permissions:

  1. Go to IAM > Policies > Create policy
  2. Select the JSON tab and paste the following (replace YOUR_BUCKET_NAME with your actual bucket name):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DXAmazonKiroReadOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}
  1. Name the policy (for example, DX-AmazonKiro-Policy) and create it

Step 3 - Create an IAM role with trust policy

Create an IAM role that DX can assume:

  1. Go to IAM > Roles > Create role
  2. Select Custom trust policy and paste the following (replace YOUR_EXTERNAL_ID_FROM_DX with the External ID from Step 1):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::703671904508:role/dx-datacloud"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_DX"
        }
      }
    }
  ]
}
  1. Click Next and attach the policy you created in Step 2
  2. Name the role (for example, DX-AmazonKiro-Role) and create it
  3. Copy the Role ARN (for example, arn:aws:iam::123456789012:role/DX-AmazonKiro-Role)

Step 4 - Configure the connection in DX

Navigate to the connections page in DX and select “+ Connection” in the top right. Enter the following in the connection form:

  • Role ARN: The ARN of the IAM role you created
  • Region: The AWS region where your S3 bucket is located
  • Bucket Name: The name of your S3 bucket containing Kiro exports
  • Connection Name: A descriptive name for this connection (for example, “Amazon Kiro Production”)
  • User mapping directory path: Path to the S3 directory containing your manually created user mapping CSV file (for example, if you uploaded your file to example/user_mapping.csv, enter example/). Note: Amazon Kiro does not automatically generate this mapping file.
  • Usage metrics directory path: Path to the directory containing Kiro usage report CSVs (for example, if your files are under example/reports/, enter example/reports/)

Click “Add connection” to establish the connection.

User mapping CSV format

Because Amazon Kiro usage reports only export internal AWS unique identifiers (aws_user_uuid), you must manually create a user mapping CSV to associate these IDs with corporate email addresses for proper reporting attribution.

Once created, you must upload this CSV to a folder in your configured S3 bucket.

How to create this file:

  1. Export your active user list from your Identity Provider (e.g., AWS IAM Identity Center or your corporate IdP) to get user emails.
  2. Correlate those users with their stable AWS User IDs (Workforce User UUIDs), which represent the aws_user_uuid.
  3. Format the CSV with the following headers (ensuring no email fields are left blank or null):

Note: The user_email column cannot be NULL or empty. Please ensure that each record has a valid email.

Tip: If you use Kiro’s usage telemetry, you may be able to source this mapping from the user activity logs. Create a user_mapping.csv and rename the relevant columns to aws_user_uuid and user_email.

How DX ingests usage data

To ensure accurate ingestion, provide the most specific S3 directory paths possible. DX scans recursively under the configured prefixes, so broad paths can unintentionally scan irrelevant files. Do not rename the exported files—DX relies on their original filename patterns to identify the correct reports.

User mapping

DX lists all objects under your configured user-mapping directory prefix (including nested subdirectories) and reads every .csv file it finds. Each file must contain both required columns:

  • aws_user_uuid
  • user_email

Usage metrics

DX lists all objects under your configured usage-metrics directory prefix (including nested subdirectories), then selects CSV files based on filename patterns. For Amazon Kiro, DX selects files whose name contains _by_user_analytic_ or _user_report_ and ends with .csv.

Best practice

Configure narrow, tool-specific folder prefixes so only the intended files are scanned, and keep the original Amazon Kiro export filenames unchanged.

API reference

The table below lists the specific AWS services and permissions that are used by DX.

Service Documentation
sts:AssumeRole Link
s3:GetObject Link
s3:ListBucket Link

Errors

The table below lists potential error codes when adding a connection in DX.

Error Description
invalid_credentials Your IAM role configuration is not valid.
access_denied DX cannot assume the IAM role. Check the trust policy and external ID.
missing_role_arn IAM role ARN is required for Amazon Kiro connections.
invalid_role_arn The IAM role ARN format is invalid. Expected format: arn:aws:iam::{account-id}:role/{role-name}
bucket_not_found The specified S3 bucket does not exist or is not accessible.
no_users_found No users found in the user mapping CSV (provide a valid user mapping CSV with aws_user_uuid and user_email columns).
no_metrics_found No usage metrics found in the provided directory.
invalid_permissions Your IAM role does not have the required permissions to access S3.