Set up a read-only IAM role

Connect your AWS account to Parsivex in about 10 minutes. This guide walks you through creating a secure, read-only IAM role that lets us analyze your cloud spending.

Why we need access

Parsivex needs read-only access to your AWS account to identify cost-saving opportunities. Here is exactly what we can and cannot do:

What we can see

What we cannot do

• Create, modify, or delete any resources
• Access your application data (database contents, S3 file contents, etc.)
• Make purchases or change your billing settings
• Access IAM credentials or secrets

The role you create uses AWS's standard cross-account access pattern with an External ID — the same security mechanism used by thousands of SaaS tools that integrate with AWS. See External ID explained for how this protects your account.

Prerequisites

Before you start, make sure you have:

• Administrator access to your AWS account (or IAM permissions to create roles and policies)
• 10 minutes of uninterrupted time
• Your Parsivex External ID (shown in the onboarding wizard when you add an AWS account, or in Integrations → AWS connections)

Don't have admin access? Forward this guide to someone on your team who does.

Step-by-step setup

Step 1: Open the IAM console

1. Sign in to your AWS Management Console
2. In the search bar at the top, type IAM and select IAM from the results
3. You should now see the IAM Dashboard

Step 2: Create a new role

1. In the left sidebar, click Roles
2. Click the Create role button (top right)

Step 3: Select trusted entity type

1. Under Trusted entity type, select AWS account
2. Under An AWS account, select Another AWS account
3. Enter the Parsivex AWS Account ID shown in your Parsivex dashboard or onboarding wizard
4. Check the box for Require external ID
5. Enter your External ID from Parsivex (format: parsivex-xxxxxxxxxxxx)
6. Click Next

Step 4: Attach the read-only policy

1. In the search box, type ReadOnlyAccess
2. Find and check the box next to ReadOnlyAccess (the AWS managed policy)
3. Click Next

For a tighter permission set, use the Parsivex minimal policy instead — see Use a more restrictive policy below.

Step 5: Name and create the role

1. For Role name, enter: ParsivexReadOnly
2. Optionally, add a description: Read-only access for Parsivex AWS cost optimization
3. Scroll down and click Create role
4. You should see a green success banner: "Role ParsivexReadOnly created"

Step 6: Copy your role ARN

1. Click on the role name ParsivexReadOnly to open it
2. At the top of the role summary, copy the ARN (Amazon Resource Name). It looks like:

arn:aws:iam::YOUR-ACCOUNT-ID:role/ParsivexReadOnly

3. Paste this ARN into the Parsivex onboarding wizard or Integrations → AWS connections when prompted

Verify your connection

After entering your Role ARN in Parsivex:

1. Click Test connection in the onboarding wizard (or Verify in Integrations)
2. Wait 10–15 seconds for the verification to complete
3. You should see a green checkmark with "Connection successful"

If the test fails, see Troubleshooting below or the dedicated Connection troubleshooting article.

Security FAQ

Is this safe?

Yes. The role you created is read-only — it cannot make any changes to your AWS account. This is the same security pattern used by AWS's own partner integrations and tools like Datadog, CloudHealth, and AWS Trusted Advisor.

What is an External ID and why do I need it?

The External ID is a secret shared between you and Parsivex. It prevents a security issue called the "confused deputy problem" where a malicious third party could trick Parsivex into accessing the wrong account. AWS recommends External IDs for all cross-account access.

Read External ID explained for a plain-English walkthrough, or AWS documentation on External IDs.

Can Parsivex access my data (database contents, files, etc.)?

No. The read-only policy only allows reading metadata and metrics — not the contents of your databases, S3 objects, or application data. We see that you have a file, not what is in it.

Use a more restrictive policy

Yes — you can use the Parsivex minimal custom policy instead of the broad AWS-managed ReadOnlyAccess. Our policy includes only the specific permissions Parsivex needs:

Automated deployment (recommended)

Use our Infrastructure-as-Code templates for one-click deployment — see Deploy with CloudFormation or Terraform for required parameters and CLI examples.

• CloudFormation — Use the Deploy with CloudFormation button in the onboarding wizard, or download the template from the security page
• Terraform — Download the Terraform module from the security page

Manual setup

If you prefer manual setup, copy the policy JSON from our security page and attach it to your role:

1. In IAM, go to Policies → Create policy
2. Click the JSON tab and paste the policy from /security
3. Name it ParsivexReadOnlyPolicy
4. When creating the role, attach this policy instead of ReadOnlyAccess

The trust policy on /security also shows the exact Principal and External ID condition Parsivex expects.

How do I revoke access?

To disconnect Parsivex from your AWS account:

1. Go to IAM → Roles in the AWS Console
2. Search for ParsivexReadOnly
3. Select the role and click Delete
4. Confirm the deletion

Access is revoked immediately. No further scans will be possible until you create a new role.

Do you store my AWS credentials?

No. We store only the Role ARN and External ID. When we need to access your account, we use AWS's AssumeRole API to get temporary credentials that expire after one hour. We never have or store long-term credentials for your account.

Troubleshooting

"Access Denied" or "Not authorized to perform sts:AssumeRole"

Cause: The trust relationship is not configured correctly.

Fix:

1. Go to IAM → Roles → ParsivexReadOnly
2. Click the Trust relationships tab
3. Click Edit trust policy
4. Verify it matches the trust policy on our security page

Make sure:

• The Account ID matches the Parsivex Account ID from your dashboard
• The External ID matches exactly (case-sensitive, no extra spaces)

"Invalid External ID"

Cause: The External ID in AWS does not match what Parsivex is sending.

Fix:

1. Copy the External ID from your Parsivex dashboard again
2. Go to IAM → Roles → ParsivexReadOnly → Trust relationships
3. Update the External ID to match exactly

See External ID explained for more context.

"Role does not exist" or "Invalid ARN"

Cause: The Role ARN was entered incorrectly in Parsivex.

Fix:

1. Go to IAM → Roles → ParsivexReadOnly
2. Copy the full ARN (starts with arn:aws:iam::)
3. Paste it in Parsivex, making sure there are no extra spaces

"Insufficient permissions" during scan

Cause: The role is missing required permissions.

Fix:

1. Verify the ReadOnlyAccess policy (or Parsivex minimal policy) is attached to the role
2. Go to IAM → Roles → ParsivexReadOnly → Permissions
3. If the policy is not listed, click Add permissions → Attach policies and attach it

Connection was working but stopped

Cause: The role may have been modified or deleted.

Fix:

1. Check that the role still exists in IAM → Roles
2. Verify the trust policy still references the correct Parsivex Account ID
3. Confirm the read-only policy is still attached

Still having trouble?

Contact us at support@parsivex.com with:

• Your AWS Account ID (visible in the top-right of AWS Console)
• The error message you are seeing
• A screenshot of your role's Trust relationships tab

We typically respond within a few hours on business days.

Next steps

Once connected, Parsivex will:

1. Run an initial scan (takes 2–5 minutes)
2. Generate your first report with identified savings
3. Email you when the report is ready

You can also view your report anytime in the Parsivex dashboard. See Your first scan for a full walkthrough.