AWS credentials and SSO profiles
CloudPouch reads the same local configuration files the AWS CLI uses — ~/.aws/credentials and ~/.aws/config — so profiles built on static credentials, IAM Identity Center (SSO), source_profile role chaining, the AWS CLI’s browser-based aws login, or an external credential_process helper work with CloudPouch. Connecting to an AWS account usually means selecting a profile you already have, not creating anything new.
If a CloudPouch error message sent you here, go straight to the matching section: your profile configuration is not supported, the role configuration is invalid, or no AWS credentials file was found.
Supported profile types
Section titled “Supported profile types”- Static IAM credentials in
~/.aws/credentials(access key and secret key). - AWS IAM Identity Center (SSO) profiles in
~/.aws/config, including the sharedsso-sessionformat where several profiles reference one session block. - Role-chaining profiles that assume a role via
source_profilein~/.aws/config. aws loginprofiles (login_session) created by the AWS CLI’s browser-based sign-in — no access keys and no Identity Center setup required.- Credential helper profiles that obtain credentials from an external command through
credential_process.
Role chains are also supported on top of helper-backed and aws login-backed profiles, without MFA. Some profile shapes are outside that scope, and Credential helpers and role chains carries the authoritative list of them.
The shared sso-session format is the practical choice when you analyze multiple AWS accounts behind one Identity Center start URL — one browser login covers every profile that references the session:
[sso-session my-company]sso_start_url = https://my-company.awsapps.com/startsso_region = eu-west-1
[profile prod]sso_session = my-companysso_account_id = 111111111111sso_role_name = ReadOnlyAccess
[profile dev]sso_session = my-companysso_account_id = 222222222222sso_role_name = ReadOnlyAccessSSO sign-in behavior
Section titled “SSO sign-in behavior”When you select an SSO profile whose session has expired or was never started, CloudPouch launches the browser-based AWS SSO sign-in flow automatically. If the browser authentication is not completed or the session is invalid, CloudPouch shows an error rather than silently continuing to display cost data from the previously active profile — so what you see always belongs to the profile you selected.
aws login profiles
Section titled “aws login profiles”A profile created by the AWS CLI’s browser-based aws login command holds an AWS Console sign-in session instead of access keys. CloudPouch works with it directly: the profile appears in the profile sidebar and works on every data screen — Billing, Compare, Cost Insights, and Savings Scan.
These profiles require AWS CLI 2.32.0 or newer — the same CLI version that created the sign-in session, because a login_session profile cannot exist without it. On a machine with no AWS CLI installed, or with an older one, CloudPouch names the problem and links to the AWS sign-in documentation instead of failing with a generic credentials error. This version requirement belongs to aws login profiles alone; a credential_process helper profile needs no AWS CLI at all.
CloudPouch never reads or stores the aws login refresh token or sign-in keys. It uses only the short-lived session credentials.
Credentials refresh during long operations
Section titled “Credentials refresh during long operations”An aws login sign-in session lasts up to 12 hours, but the session credentials inside it live only 15 minutes. CloudPouch refreshes those credentials transparently in the background, with no action from you, which is why a Savings Scan that runs longer than 15 minutes keeps going instead of failing part way through. Credential helper profiles get the same treatment: CloudPouch refreshes helper-issued credentials automatically when they expire.
Re-authenticating an expired sign-in session
Section titled “Re-authenticating an expired sign-in session”When the sign-in session itself expires — after up to 12 hours, or after you run aws logout — CloudPouch shows a prompt that names the affected profile and gives you the exact command to fix it:
aws login --profile <name>A button next to it copies the command to your clipboard. The prompt appears in Billing, Compare, single-service Cost Insights, and the Savings Workspace, and it is the same prompt in all four. In the Savings Workspace it replaces the results area for that scan attempt, so an old run is never left sitting next to the warning as if it were current. Revoking a login grant on the AWS side is treated the same way: you get the re-authentication prompt, not a different error.
Credential helper profiles
Section titled “Credential helper profiles”A profile whose credential_process names an external credential helper — off-the-shelf or in-house — works everywhere a profile is used in CloudPouch. The support is generic: CloudPouch runs whatever command the profile names, without a shell, and uses the short-lived credentials it prints.
Credential helpers and role chains is the reference for this: exactly which helper and role-chain shapes CloudPouch resolves, which it does not, and what a failing helper looks like.
Finding and reloading profiles
Section titled “Finding and reloading profiles”Profiles without a credentials file
Section titled “Profiles without a credentials file”CloudPouch lists your profiles correctly on a machine that has never had an ~/.aws/credentials file — a machine that has only ever used aws login, for example. Profiles defined in ~/.aws/config are enough. CloudPouch also honors the AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE environment variables when it looks for profile configuration, so a non-default file location works as long as CloudPouch inherits those variables.
Reload AWS profiles without restarting
Section titled “Reload AWS profiles without restarting”Press Cmd + R on macOS, or Ctrl + R on Windows and Linux, to reload the profile list. The same action is available from the native application menu and from the AWS Profiles (Accounts) header in the sidebar.
The list refreshes in place: your current view, the results already in memory, and any scan still running all survive the reload. A profile created while CloudPouch is open — running aws login --profile new-client in a terminal, or editing ~/.aws/config — shows up immediately, with no restart.
Switching between profiles
Section titled “Switching between profiles”Cost work usually spans accounts, so profile switching is a first-class action:
- Press
Cmd/Ctrl + Kto open the quick AWS profile switcher (Search AWS profiles…). - Type to filter by profile name, move with
Up/Down, select withEnter, close withEsc. - The switcher covers every profile CloudPouch resolves: named profiles, SSO profiles,
aws loginprofiles, credential helper profiles, and the supported role chains.
If ~/.aws/credentials has no default profile, CloudPouch shows a welcome screen instead of failing on startup.
Credential precedence and what has not changed
Section titled “Credential precedence and what has not changed”Static-key, assume-role, and IAM Identity Center (SSO) profiles behave exactly as they did before aws login and credential_process support existed. Adding those two profile types changes nothing about how an existing profile resolves — nothing you already had needs reconfiguring.
When one profile mixes credential types (say a profile carrying both static keys and a credential_process line), CloudPouch checks it in a fixed order and uses the first mechanism it finds: static keys, then an assumed role (role_arn), then IAM Identity Center (SSO), then aws login (login_session), then credential_process. That order follows the AWS CLI’s for the combinations people actually write, but it is not identical to it: for example, static keys in ~/.aws/config win over credential_process here, while the AWS CLI ranks them the other way round. aws sts get-caller-identity --profile <name> therefore shows which identity the AWS CLI picks, not necessarily which one CloudPouch picks. The reliable fix for a mixed profile is to remove the mechanism you do not want it to use.
Setting up a profile for CloudPouch
Section titled “Setting up a profile for CloudPouch”- Configure the profile with the AWS CLI (
aws configure,aws configure sso, oraws login), or point it at your credential helper withcredential_process. - Verify it can read the account you want to analyze — for example,
aws sts get-caller-identity --profile prod. - Open CloudPouch and select the profile.
The permissions attached to that profile are all CloudPouch gets — it needs read access only. See AWS read-only access for the model and AWS permissions for a ready-made policy.
When CloudPouch cannot use your profile
Section titled “When CloudPouch cannot use your profile”CloudPouch says your profile configuration is not supported
Section titled “CloudPouch says your profile configuration is not supported”CloudPouch resolves the profile shapes listed under Supported profile types. A defined set of other shapes — mostly MFA-gated profiles and profiles that source their credentials from somewhere CloudPouch does not read — sits outside that scope, and the message names the profile it could not resolve.
Open Credential helpers and role chains and find your profile’s shape in the list there. That list is the authoritative one, and where a workaround exists it sits next to the entry. The usual one is to let a credential helper do the work CloudPouch cannot — MFA prompting, in particular — and point a wrapper profile’s credential_process at that helper, which is a shape CloudPouch does resolve.
Note that the profile may still work perfectly with the AWS CLI. The AWS CLI supports profile shapes CloudPouch does not, so “it works in the terminal” does not mean the profile is misconfigured.
CloudPouch says the role configuration is invalid
Section titled “CloudPouch says the role configuration is invalid”This one is about the role-assumption part of the profile rather than the credentials underneath it. Check, in ~/.aws/config:
- The
source_profileexists and names a profile CloudPouch itself resolves. A chain is only as good as the profile at its root. role_arnidentifies the role you intend to assume — a complete role ARN for a role the source identity is allowed to assume. Confirm withaws sts assume-roleor by selecting the profile in the AWS CLI.
Then check your chain against Credential helpers and role chains, which lists the supported configurations, the profile shapes CloudPouch does not resolve, and the workarounds available for some of them.
CloudPouch cannot find an AWS credentials file
Section titled “CloudPouch cannot find an AWS credentials file”CloudPouch does not need ~/.aws/credentials to exist. Profiles defined in ~/.aws/config are enough, which is what makes an aws login-only or helper-only machine work. If CloudPouch reports that it found no credentials file and no profiles:
- Check that
~/.aws/configexists and defines at least one profile. On a fresh machine neither file exists until you runaws configure,aws configure sso, oraws login. - Check the file location overrides. If you keep AWS configuration somewhere else,
AWS_CONFIG_FILEandAWS_SHARED_CREDENTIALS_FILEmust be visible to CloudPouch itself. An export in your shell profile reaches a terminal-launched process but does not necessarily reach an application launched from the Dock or Start menu. - Check the profile heading syntax. Profiles in
~/.aws/configneed the[profile name]form, while~/.aws/credentialsuses bare[name]. A profile written the wrong way in the wrong file is invisible to the AWS CLI and to CloudPouch alike. - Reload after fixing it. Press
Cmd + R(macOS) orCtrl + R(Windows and Linux) — no restart needed.