Connect AWS to Xplorr: IAM Role Setup for Cloud Cost Data

import { Steps } from ‘@astrojs/starlight/components’;

Connect AWS to Xplorr

Xplorr reads your AWS billing data through the Cost Explorer API. You grant access by creating a cross-account IAM role in your AWS account that Xplorr assumes with read-only permissions. No access keys are stored on the Xplorr side — just a trust relationship.

Two Connection Methods

Method	Best For	Setup Time
IAM Role (recommended)	Production use. No long-lived keys.	~5 min
Access Keys	Quick testing, personal accounts.	~2 min

The IAM Role method is strongly recommended. It uses AWS STS AssumeRole with an external ID, which means Xplorr never stores your AWS credentials — it generates temporary session tokens on each sync.

Method 1: IAM Role (Recommended)

Start the connection in Xplorr

Log in to console.xplorr.io. Go to Settings > Cloud Accounts > Add Account > Amazon Web Services.

Select IAM Role as the connection method. You’ll see two values you need for the next step:
- Xplorr AWS Account ID: 891377174505
- External ID: A unique string generated for your organization (looks like xplorr-ext-abc123def456)
Copy both. Keep this tab open.

Create the IAM policy in AWS

Open the AWS IAM Console and create a new policy with this JSON:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "XplorRCostExplorer",
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostAndUsageWithResources",
        "ce:GetCostForecast",
        "ce:GetReservationUtilization",
        "ce:GetReservationCoverage",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansCoverage",
        "ce:GetDimensionValues",
        "ce:GetTags",
        "ce:DescribeCostCategoryDefinition",
        "ce:ListCostCategoryDefinitions",
        "ce:ListCostAllocationTags"
      ],
      "Resource": "*"
    },
    {
      "Sid": "XplorRResourceInventory",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeVolumes",
        "ec2:DescribeSnapshots",
        "elasticloadbalancing:DescribeLoadBalancers",
        "rds:DescribeDBInstances",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "XplorROrganizations",
      "Effect": "Allow",
      "Action": [
        "organizations:ListAccounts",
        "organizations:DescribeOrganization"
      ],
      "Resource": "*"
    }
  ]
}

Name the policy XplorrReadOnly. This is entirely read-only — no write, delete, or modify permissions.

Create the IAM role

In the IAM Console, go to Roles > Create role:
- Trusted entity type: Another AWS account
- Account ID: 891377174505 (Xplorr’s AWS account)
- Require external ID: Yes — paste the external ID from step 1
- Permissions: Attach the XplorrReadOnly policy you just created
- Role name: XplorrReadOnly
After creation, copy the Role ARN. It looks like: arn:aws:iam::123456789012:role/XplorrReadOnly
Paste the Role ARN into Xplorr

Go back to the Xplorr tab. Paste the Role ARN and click Connect.

Xplorr will immediately validate the role by calling sts:AssumeRole. If it succeeds, the initial data sync starts. First sync takes 2-5 minutes for a typical account (a few months of data). Accounts with years of history may take up to 30 minutes.

What Is the External ID?

The external ID prevents the “confused deputy” attack. Without it, any AWS account that knows Xplorr’s account ID could potentially trick Xplorr into assuming a role in their account. The external ID is a shared secret between your account and Xplorr — it’s unique per organization and must match exactly in both the IAM trust policy and the Xplorr connection form.

If you see a mismatch error, copy the external ID from Xplorr again and update the trust policy in your IAM role.

CloudFormation Quick Setup

If you prefer automated setup, use this CloudFormation template. It creates the policy and role in one click:

AWSTemplateFormatVersion: '2010-09-09'
Description: Xplorr read-only IAM role for cloud cost data access
Parameters:
  ExternalId:
    Type: String
    Description: External ID from Xplorr console
Resources:
  XplorrRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: XplorrReadOnly
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: 'arn:aws:iam::891377174505:root'
            Action: 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId': !Ref ExternalId
      Policies:
        - PolicyName: XplorrReadOnlyPolicy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - 'ce:Get*'
                  - 'ce:Describe*'
                  - 'ce:List*'
                  - 'ec2:DescribeInstances'
                  - 'ec2:DescribeRegions'
                  - 'ec2:DescribeVolumes'
                  - 'ec2:DescribeSnapshots'
                  - 'elasticloadbalancing:DescribeLoadBalancers'
                  - 'rds:DescribeDBInstances'
                  - 'cloudwatch:GetMetricData'
                  - 'organizations:ListAccounts'
                  - 'organizations:DescribeOrganization'
                Resource: '*'
Outputs:
  RoleArn:
    Value: !GetAtt XplorrRole.Arn
    Description: Paste this ARN into the Xplorr console

Upload this in the CloudFormation Console, paste your External ID when prompted, and copy the Role ARN from the Outputs tab.

Method 2: Access Keys

Create an IAM user

In the AWS IAM Console, create a new user (e.g., xplorr-readonly). Attach the same XplorrReadOnly policy from above.
Generate access keys

Go to the user’s Security credentials tab and click Create access key. Select “Third-party service” as the use case. Copy the Access Key ID and Secret Access Key.
Enter credentials in Xplorr

In the Xplorr console, go to Settings > Cloud Accounts > Add Account > AWS and select Access Keys. Paste the Access Key ID, Secret Access Key, and select your primary region (e.g., us-east-1).

Connecting Multiple AWS Accounts

Using AWS Organizations: Connect your management (payer) account first. Xplorr pulls consolidated billing data for all member accounts through it. You don’t need to create IAM roles in each member account.

Individual accounts: If you don’t use AWS Organizations, or want to pull resource-level data from specific accounts, repeat the IAM Role setup for each account.

Verify the Connection

After connecting, go to Settings > Cloud Accounts. Your AWS account should show:

Status: Green “Connected” badge
Last synced: A timestamp within the last few minutes
Accounts: The number of member accounts (if using Organizations)

You can also verify via the MCP server or API:

curl https://api.xplorr.io/api/v1/accounts \
  -H "Authorization: Bearer xplorr_your_token_here"

Common Mistakes

Forgetting to enable AWS Cost Explorer. Cost Explorer must be enabled in the AWS console before Xplorr can pull data. Go to the AWS Cost Explorer page and click “Enable Cost Explorer” if you haven’t already. Data takes up to 24 hours to become available after first enabling it.
Wrong external ID. The external ID in the IAM role trust policy must match exactly what Xplorr shows. If you regenerate the connection in Xplorr, the external ID changes.
Using the wrong Xplorr account ID. The trusted entity must be 891377174505. Double-check there are no extra spaces or characters.
Attaching policies to the wrong role. If you have multiple IAM roles, make sure the XplorrReadOnly policy is attached to the role whose ARN you pasted into Xplorr.

Troubleshooting

AccessDenied or AssumeRole failed

Verify the external ID matches between Xplorr and your IAM role trust policy
Verify the trusted entity account ID is 891377174505
Check that the XplorrReadOnly policy is attached to the role
Run this AWS CLI command to test the role locally:

aws sts assume-role \
  --role-arn arn:aws:iam::YOUR_ACCOUNT_ID:role/XplorrReadOnly \
  --role-session-name test \
  --external-id YOUR_EXTERNAL_ID

InvalidClientTokenId

Your access keys are invalid or inactive. Go to IAM > Users > your user > Security credentials and verify the keys are active. Regenerate if needed.

No cost data appears after sync

AWS Cost Explorer data lags up to 24 hours. Wait a day if this is a new account or you just enabled Cost Explorer.
Trigger a manual re-sync from Settings > Cloud Accounts > Sync.
Verify the IAM policy includes ce:GetCostAndUsage — the ReadOnlyAccess managed policy does NOT include Cost Explorer permissions.

Data only shows for management account, not member accounts

Make sure the IAM policy includes organizations:ListAccounts. Without it, Xplorr can only see the payer account.

Setup Checklist

AWS Cost Explorer is enabled in your account
IAM policy created with Cost Explorer, EC2, and Organizations read permissions
IAM role created with Xplorr’s account ID (891377174505) as trusted entity
External ID matches between IAM role and Xplorr connection form
Role ARN pasted into Xplorr
Connection shows “Connected” with a recent sync timestamp
Dashboard shows cost data for your account

FAQ

Is the access truly read-only? Yes. The IAM policy only includes Get*, Describe*, and List* actions. Xplorr cannot create, modify, or delete any AWS resource.

Which AWS regions does Xplorr pull data from? Cost Explorer is a global service — it returns billing data across all regions. Resource inventory (EC2, RDS, ELB) is pulled from all enabled regions in your account.

How often does Xplorr sync data? Every 6 hours by default. You can trigger a manual sync anytime from the dashboard or via the trigger_sync MCP tool.

Does Xplorr support AWS GovCloud? Not currently. Xplorr connects to standard AWS commercial regions.

Can I restrict access to specific services? Yes. Modify the IAM policy to limit ce:GetCostAndUsage to specific dimensions. However, this will reduce the data available in Xplorr.

Connect Azure — Service Principal setup for Azure cost data
Connect GCP — Service account and BigQuery billing export
Budget Alerts — Set spending limits after connecting your account