Migrating to Fine-Grained IAM Policies

AWS deprecated a set of legacy IAM actions used to control access to Billing, Cost Management, and Account consoles. If your AWS account was created before March 6, 2023, you likely have policies that still use these old actions — and they need to be updated before AWS Billing Transfer will work correctly to onboard to Cloud Capital. This guide explains why the migration is required, how to check if you’re AWS IAM policies are affected, and how to complete the update using AWS’s built-in tooling.

AWS Billing Transfer requires that your IAM policies use the new fine-grained actions. Accounts with legacy aws-portal:* policies may encounter permission errors or incomplete data visibility during onboarding. Complete this migration before enabling the integration in Cloud Capital.

Background: What changed and why

AWS previously used a broad set of IAM actions under the aws-portal namespace to control access to billing and cost management features. These coarse-grained actions made it difficult to grant targeted access — for example, allowing an engineer to view cost data without also giving them access to payment methods or account settings. AWS replaced these with a new set of fine-grained IAM actions spread across multiple service prefixes:

New service prefix	What it controls
`billing`	Billing console, invoices, and billing data
`payments`	Payment methods and preferences
`invoicing`	Invoice configuration and delivery settings
`freetier`	AWS Free Tier visibility
`consolidatedbilling`	Consolidated billing for AWS Organizations
`tax`	Tax settings and documents
`account`	Account-level settings and contacts
`cur`	Cost and Usage Reports
`purchase-orders`	Purchase order management

The old aws-portal:* actions, along with certain purchase-orders actions, are retired. Policies still referencing them will eventually stop working — and some AWS features, including Billing Transfer, require the new permissions to function correctly.

If your AWS account or AWS Organization was created on or after March 6, 2023, fine-grained actions are already enforced for you. You can skip ahead to verify you’re not affected.

Checking whether you are affected

AWS provides an Affected Policies Tool directly in the Billing console. It scans your IAM policies (not SCPs) and identifies any that still reference deprecated actions.

Open the AWS Billing console

Navigate to https://console.aws.amazon.com/billing and sign in with an account that has billing console access.

Find the Affected Policies Tool

In the left navigation, go to Billing preferences → Affected Policies. If this section isn’t visible, your account may already be fully migrated.

Review the results

The tool lists every IAM policy that references deprecated actions. Each entry shows:

The policy name and ARN
The specific deprecated actions detected
A suggested updated policy you can copy directly

If the list is empty, no action is required and you’re ready to proceed with Cloud Capital onboarding.

If you manage an AWS Organization, run this check from your payer (management) account — it provides the broadest view of affected policies across the organization. Member accounts may also have their own affected policies that require separate review.

Migrating your policies

Once you’ve identified affected policies, you have two options: use the Affected Policies Tool to copy-paste updated versions, or update policies manually if you manage them in code.

Using the Affected Policies Tool (recommended)
Updating policies in code (IaC / version control)

The tool generates an updated version of each affected policy for you — you don’t need to hand-write the new actions.

Copy the updated policy

In the Affected Policies table, find the policy you want to update. Under the Copy updated policy column, click Copy.The copied policy includes your existing policy statements plus a new Sid block (prefixed AffectedPoliciesMigrator) containing the equivalent fine-grained actions.

Open the policy in IAM

Navigate to IAM → Policies, search for the policy by name, and click into it.

Edit and paste the updated policy

Click Edit policy → switch to the JSON tab → replace the existing policy document with the one you copied → click Review policy → Save changes.

Repeat for all affected policies

Return to the Affected Policies Tool and repeat this process for each policy listed.

Verify the migration is complete

After updating all policies, refresh the Affected Policies Tool. If the list is now empty, your migration is complete.

Keep the old aws-portal:* actions in place during the migration period. The updated policy generated by the tool retains them alongside the new fine-grained actions. This ensures continuity of access while AWS completes the deprecation process. Once fully migrated, you can safely remove the old actions.

If your IAM policies are managed via Terraform, CloudFormation, CDK, or a version-controlled JSON/YAML source, you’ll need to apply the same changes to those definitions — not just in the AWS console.Use the AWS old-to-new action mapping reference to identify the fine-grained equivalents for each aws-portal:* action in your policies.A typical before/after looks like this:

Before (legacy)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ViewBillingAccess",
      "Effect": "Allow",
      "Action": [
        "aws-portal:ViewBilling",
        "aws-portal:ViewPaymentMethods"
      ],
      "Resource": "*"
    }
  ]
}

After (fine-grained — example structure)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ViewBillingAccess",
      "Effect": "Allow",
      "Action": [
        "aws-portal:ViewBilling",
        "aws-portal:ViewPaymentMethods"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AffectedPoliciesMigratorViewBillingAccess",
      "Effect": "Allow",
      "Action": [
        "billing:GetBillingData",
        "billing:GetBillDetails",
        "billing:GetConsoleActionSetEnforced",
        "payments:ListPaymentPreferences",
        "payments:GetPaymentInstrument"
      ],
      "Resource": "*"
    }
  ]
}

The exact fine-grained actions that map to your existing permissions will vary. Use the Affected Policies Tool output as your authoritative reference — it generates the correct replacement actions for each specific policy.

After updating your IaC definitions, deploy the changes and then use the Affected Policies Tool to confirm the console-visible policies are updated as well.

Frequently asked questions

Will my team lose access during the migration?

No — as long as you retain the old aws-portal:* actions in your policy during the transition, access remains uninterrupted. The migration adds new fine-grained actions alongside the existing ones; it does not remove the old ones until you’re ready.

Does this affect Service Control Policies (SCPs)?

The Affected Policies Tool only scans IAM identity-based policies. SCPs are not included in the scan. If your organization uses SCPs to restrict billing or cost management access, review those separately using the action mapping reference and update them manually if needed.

I manage multiple AWS accounts. Do I need to do this for each one?

Yes, but you can get a consolidated view from your payer (management) account. For large organizations, AWS provides Bulk Policy Migrator Scripts that can help automate updates across member accounts.

What happens if I don't migrate before enabling AWS Billing Transfer?

You may encounter permission errors during Cloud Capital onboarding, or some cost and billing data may not flow through correctly. We recommend completing the migration before enabling the integration to ensure a smooth setup.

My account was created after March 6, 2023. Do I need to do anything?

No — accounts created on or after that date already enforce fine-grained actions by default. The Affected Policies Tool will show an empty list, and you’re ready to proceed with Cloud Capital onboarding.

Next steps

Once your IAM policies are updated and the Affected Policies Tool shows no remaining issues, you’re ready to enable AWS Billing Transfer in Cloud Capital.

Enable AWS Billing Transfer

Connect your AWS payer account to Cloud Capital to start ingesting billing and cost data.

AWS fine-grained permissions reference

Official AWS documentation on migrating access control for Cost Management.

Official AWS reference: This guide is based on AWS’s own documentation for migrating Billing and Cost Management IAM policies. For the full action mapping and organizational migration scripts, see the AWS Cost Management migration guide and the Affected Policies Tool reference.

Overview

Quickstart

Integration

Financial Onboarding

Forecasting

Cost Optimization

AI Agent & Tools

Settings

Security

Glossary

Background: What changed and why

Checking whether you are affected

Migrating your policies

Frequently asked questions

Next steps

Enable AWS Billing Transfer

AWS fine-grained permissions reference

Overview

Quickstart

Integration

Financial Onboarding

Forecasting

Cost Optimization

AI Agent & Tools

Settings

Security

Glossary

Documentation Index

​Background: What changed and why

​Checking whether you are affected

​Migrating your policies

​Frequently asked questions

​Next steps

Enable AWS Billing Transfer

AWS fine-grained permissions reference

Background: What changed and why

Checking whether you are affected

Migrating your policies

Frequently asked questions

Next steps