Connect an AWS account

Connect an AWS account and your agents can run aws --profile <name> … against it straight away. Agents only ever get short-lived credentials, and you decide which roles they can use.

This page covers the four ways to connect, choosing roles, what the agent gets, and how access is secured and revoked.

Before you start

• You need permission to manage connections at the scope you’re connecting to. See Connection scopes.
• Use the dashboard at app.alfe.ai or the desktop app. The mobile app lists AWS connections but can’t add or manage them.
• Have access to the AWS account. For the role method, you need permission to create a CloudFormation stack and an IAM role.
• Use an account in the standard (commercial) AWS partition. AWS GovCloud (US) and AWS China accounts can’t be connected.

Choose a connection method

Pick the method that matches how long agents need access:

Method	Best for	Agents act as	Access lasts
Connect with a role (recommended)	Always-on agents	An IAM role you create	Until you revoke it
Use access keys	Accounts where you can’t create a role	An IAM user	Until you revoke it
Sign in with AWS SSO	Work sessions with your own access	You	Until your AWS SSO session ends
Share a session from your laptop	One agent, for a short task	You	Until the shared session expires

• Connect with a role — you create an IAM role in your account with one click. Alfe assumes it with an external ID that only your setup link carries. No long-lived keys are shared.
• Use access keys — you paste the access key of an IAM user. Alfe stores the keys encrypted and never sends them to an agent. Root account keys are always rejected.
• Sign in with AWS SSO — you sign in with your IAM Identity Center login and pick the accounts and roles agents may use. Nothing to create in AWS.
• Share a session from your laptop — you run alfe aws share after aws sso login, and one agent borrows that session.

Prefer the role method for agents that work around the clock. It needs no key rotation, it doesn’t depend on anyone staying signed in, and its Direct profile can call IAM APIs. The access-keys Direct profile can’t; see Limitations.

Use AWS SSO or a shared session when you want an agent to work with your own access for a while. Both act as you, so read How SSO and shared sessions act as you first.

Connect with a role

1. In the Connections hub, choose the scope, then select Add new connection and pick AWS.
2. Select Connect with a role.
3. Under What can agents do in this account?, choose an access level. See Access levels for what each one grants.
4. Leave Let the agent switch into other roles ticked if agents should use other roles in your accounts. Untick it to limit agents to this one role. See Role chaining.
5. Select Launch in AWS. AWS CloudFormation opens in a new tab with every parameter filled in.
6. Sign in to AWS if prompted, acknowledge that the stack creates IAM resources, and select Create stack.
7. Back in Alfe, enter your 12-digit AWS account ID. You can paste the role ARN instead; the stack’s RoleArn output shows it.
8. Pick a Default region and, optionally, a Label such as “Production”. Then select Continue.

Alfe verifies that it can assume the new role. It also checks that the role refuses requests without the external ID, and rejects a role that doesn’t. If the stack is still finishing, you’ll see Waiting for AWS… while Alfe retries for up to 30 seconds. Next, choose the roles agents can use.

Note

CloudFormation opens in us-east-1. IAM roles are global, so the role works in every region. The default region only sets where agent commands run when they don’t pass --region.

What the stack creates

The stack creates one IAM role, named AlfeAgentAccess-…. The role:

• Trusts one Alfe principal — and only when the request carries the external ID from your setup link. You can see both in the role’s trust policy.
• Has the AWS managed policy for your access level attached.
• Can discover other roles — an inline policy named AlfeDiscoveryAndChaining allows iam:ListRoles, iam:ListAccountAliases, and organizations:ListAccounts.
• Can or can’t switch into other roles — the same policy allows sts:AssumeRole when role chaining is on, and explicitly denies it when it’s off.
• Has a maximum session duration of one hour.

The stack’s AllowRoleChaining parameter holds your choice: Yes (the default) or No.

Role chaining

Role chaining lets the Alfe role switch into other roles, so agents can use the roles you select in Choose the roles agents can use. It’s on by default.

With chaining on, the role can assume any role, in any account, whose trust policy trusts this role or this account. That includes a role that trusts arn:aws:iam::<ACCOUNT_ID>:root with no conditions. Such a role can grant more than the access level you picked.

The profiles you select decide which roles Alfe issues credentials for. They don’t limit the role itself: an agent using the Direct profile can call sts:AssumeRole with it. The real boundary is the trust policies in your accounts, so check which roles trust this account before you leave chaining on.

Turn chaining off when agents only need the Alfe role itself. The explicit deny overrides every access level, including Administrator. Role discovery still works, but you can only save the Direct profile. To add chained roles later, select Re-issue link and run the update with chaining turned on.

Access levels

The access level picks the AWS managed policy attached to the role:

Access level	AWS managed policy	What agents can do
Read-only (default)	ReadOnlyAccess	Look at everything, change nothing.
Power user	PowerUserAccess	Create and change resources, but not IAM users, roles, or account settings.
Administrator	AdministratorAccess	Full control of the account, including IAM.

The access level covers the Alfe role only. Chained roles carry their own permissions; see Role chaining.

Administrator at the organization level

A connection at the organization scope is available to every team, project, and agent. Choosing Administrator there gives all of them full control of the account. Prefer Read-only or Power user, or connect at a single agent’s scope instead.

Connect with access keys

1. In the Connections hub, choose the scope, then select Add new connection and pick AWS.
2. Select Use access keys.
3. Enter the IAM user’s Access key ID and Secret access key. The key ID must be a long-term key that starts with AKIA. Temporary ASIA keys and root account keys are rejected.
4. Pick a Default region and, optionally, a Label. Then select Continue.

Alfe checks the keys with AWS. Next, choose the roles agents can use.

Choose the roles agents can use

This step applies to the role and access-key methods. AWS SSO has its own accounts and roles step, and a shared session gives the agent one profile.

After verifying, Alfe shows the identities agents can use. Each one you tick becomes a named AWS CLI profile on the agent.

• Direct — the connected identity itself: the Alfe role, or the IAM user behind your access keys. It’s ticked by default.
• Discovered roles — roles Alfe found that may trust the connected identity. These include roles whose trust policy names your account. If you use AWS Organizations, they also include standard roles in member accounts, such as OrganizationAccountAccessRole.
• Role ARN — add any role discovery missed by pasting its ARN.

Discovered roles are candidates until you save. If the identity isn’t allowed to list roles, or the list is cut short, Alfe says so and you can still add roles by ARN. If you turned role chaining off, you can only save the Direct profile.

To finish:

1. Tick the identities agents should use.
2. Edit each profile name if you like. Names use lower-case letters, numbers, -, and _, up to 63 characters. Each must be unique, and default is reserved.
3. Select Save and activate.

Alfe test-assumes every selected profile. If one fails, it’s flagged inline and nothing is activated. Fix or untick it, then save again. When every profile passes, the connection becomes Active.

To change the roles later, select Manage roles on the connection.

Sign in with AWS SSO

Sign in with your AWS IAM Identity Center login, and agents can use the accounts and roles you pick. You sign in on AWS’s own page, so Alfe never sees your password or MFA.

1. In the Connections hub, choose the scope, then select Add new connection and pick AWS.
2. Select Sign in with AWS SSO.
3. Enter your AWS access portal URL. It’s the address you open to sign in to AWS, and the sso_start_url value in ~/.aws/config. Alfe accepts either form:
   • https://<YOUR_NAME>.awsapps.com/start
   • https://ssoins-<INSTANCE_ID>.portal.<REGION>.app.aws
4. Check the SSO region: where your IAM Identity Center lives, and the sso_region value in ~/.aws/config. An app.aws portal URL fills it in for you.
5. Pick a Default region, then select Sign in with AWS.
6. Alfe shows a code and opens the AWS sign-in page. Check that the code on the AWS page matches, then select Allow. If no page opened, select Open AWS sign-in.
7. Under Choose accounts and roles, tick each account and role pair agents may use. Each becomes an AWS CLI profile; edit its name if you like.
8. Select Connect. If other people can use this AWS access, Alfe shows a warning first. Read it, tick I understand, then select Connect again. See When other people can use your access.

Alfe tests every pair you ticked. If one fails, it’s flagged inline; fix or untick it, then save again. The list shows only accounts and roles your AWS SSO user is assigned. If you have none, ask your AWS admin to assign you a permission set.

Once connected, the connection shows AWS credentials last up to <n>h. That’s the session duration of your permission set in AWS. We recommend setting it to 1 hour; see How long credentials stay valid.

A sign-in code lasts about 10 minutes. If it expires, or you cancel on the AWS page, select Start again for a new code.

Only approve codes you started

The AWS approval page names the requester: Alfe, your organization, and your email address. If you didn’t start the sign-in, or the page names someone else, don’t approve it. Approving gives that request your AWS access.

Who can manage an SSO connection

The connection uses your AWS identity, so only you can change it:

• Manage roles and Sign in again appear only for the person who signed in.
• Anyone who can manage connections at that scope can still disconnect it.
• An SSO connection can’t be moved to another scope. Disconnect it and sign in again at the new scope.

Above a single agent, every agent acts as you

An SSO connection at a team, project, or organization scope is shared with every agent there. All of them use AWS as you, with your access, so Alfe asks you to tick I understand first. To limit it to one agent, add it from that agent’s Connections tab.

Sign in again when your session ends

Your access lasts as long as your IAM Identity Center session. When it ends, the connection shows Sign-in expired and agents get an error asking you to sign in again. Their profiles stay in place.

To restore access, select Sign in again on the connection and approve the new code. Agents get access back with the same accounts and roles.

Share a session from your laptop

Share the AWS session on your own computer with one agent, for as long as that session lasts. You don’t create anything in AWS or in the dashboard.

Requirements

• Alfe CLI, signed in as you — run alfe login on your own computer. The command refuses to run with an agent’s login.
• AWS CLI v2.9 or later — alfe aws share reads your session with aws configure export-credentials, which needs v2.9.
• A profile with temporary credentials — an IAM Identity Center (SSO) profile or a role profile. Profiles with long-term access keys are refused; connect access keys in the dashboard instead.
• Permission to manage connections for the agent you share with.

Share and stop a session

1. Sign in to AWS on your computer:

   Terminal

   aws sso login --profile <LOCAL_PROFILE>

2. Share the session with an agent. Pass the agent’s name or ID:

   Terminal

   alfe aws share --profile <LOCAL_PROFILE> --agent <AGENT>

   Output

   Shared AWS profile "dev" (account 123456789012) with Ravi. Expires 2026-10-16T09:00:00.000Z (in 59 min).
   On the agent: aws --profile dev sts get-caller-identity

3. To remove the session before it expires, run:

   Terminal

   alfe aws share --agent <AGENT> --as <NAME> --stop

The credentials are checked on your computer and sent once to Alfe. They’re never printed or written to disk. Share again with the same name to replace the session, for example after a fresh aws sso login.

Command options

Option	What it does
--profile <local>	Local AWS CLI profile to export credentials from. Required to share.
--agent <name|id>	Agent to share with, by ID or exact name. Always required.
--as <name>	Profile name on the agent. Defaults to the local profile name; default becomes aws-session.
--region <region>	Default region on the agent. Defaults to the profile’s region, else us-east-1.
--watch	Keep sharing refreshed credentials until you press Ctrl+C.
--stop	Remove the shared session from the agent. Needs --as, or the --profile you shared.
--confirm-shared	Share even when other people can use the agent. Needed when there’s no terminal to answer the prompt.

If other people can chat with the agent, the command prints a warning and asks Share your AWS session with <AGENT> anyway?. Answer y to share. In a script or any run without a terminal, pass --confirm-shared instead. See When other people can use your access.

Keep a session alive with --watch

A shared session ends when the credentials you exported expire. Add --watch to keep the agent working while your local session lasts:

Terminal

alfe aws share --profile <LOCAL_PROFILE> --agent <AGENT> --watch

The command re-exports your credentials about 10 minutes before they expire and shares them again. If the export fails, it retries with a growing delay. Run aws sso login again in another terminal to recover.

When you press Ctrl+C, the shared profile stays usable until its current expiry. Run the --stop command to remove it sooner.

In the dashboard, a shared session appears on the agent’s connections as Shared session with its expiry, and shows Expired once it ends. It has no roles to manage; share again from your laptop, or disconnect it.

How SSO and shared sessions act as you

AWS SSO and shared sessions give agents your own AWS identity, not a role built for Alfe. That’s what makes them quick to set up, and it has tradeoffs:

• Alfe holds your sign-in. For AWS SSO, Alfe keeps your sign-in, encrypted, until it ends. It can reach every account and role your SSO user has, but Alfe only issues credentials for the pairs you picked, and only you can change them.
• CloudTrail shows you. AWS records agent calls under your own identity, such as your SSO user, not an alfe-<agentId> session. Agent activity and your own look alike.
• Issued credentials outlive changes in Alfe. Disconnecting stops new credentials, but ones already issued keep working at AWS until they expire.
• Access ends with your session. New credentials stop when your IAM Identity Center session ends. Your AWS admin sets its length; the AWS default is 8 hours.

For agents that must keep working when you’re offline, use Connect with a role.

When other people can use your access

Anyone who can make the agent act can use your AWS access. That includes other members of your organization who can chat with the agent, and anyone with the agent’s public chat link. AWS CloudTrail shows their actions as yours.

Alfe warns you before it saves an SSO or shared-session connection when:

• The agent is in an organization — other members may be able to chat with it.
• The agent has a public chat link — anyone with the link can chat with it.
• The connection is above a single agent — every agent at that team, project, or organization scope acts as you.

In the dashboard, tick I understand to continue. With alfe aws share, answer y at the prompt or pass --confirm-shared. The connection then shows a Shared AWS access badge; hover over it to see who can use it.

No warning doesn’t mean private

The warning covers the cases above, but not every way someone can reach an agent. In a personal account, chat access you’ve granted to specific people or contacts, and partner access to your account, don’t trigger it. Before sharing your AWS access, check who can chat with the agent.

For an agent other people use, prefer Connect with a role with only the permissions that agent needs.

How long credentials stay valid

Agents fetch new credentials about every hour. Credentials already issued keep working at AWS until AWS expires them, and Alfe can’t shorten that:

• AWS SSO — credentials last for the permission set’s session duration. That’s 1 hour by default and up to 12 hours. The connection shows the value as AWS credentials last up to <n>h.
• Shared session — credentials last until the session you shared expires, up to 12 hours.

So after you untick a role, disconnect, or your sign-in ends, an agent may still hold working credentials for up to that long. Set the permission set’s session duration to 1 hour in IAM Identity Center to keep that window short. To cut access sooner, revoke it in AWS; see Revoke access.

Give your agent the AWS CLI

The connection holds the access. The AWS integration puts it to work on the agent. You don’t need to install it: once the connection is Active, Alfe adds it automatically to every agent that can see the connection, and removes it when the last AWS connection goes away.

The integration:

• Installs AWS CLI v2 on the agent host.
• Writes one named profile per selected identity into ~/.aws/config.
• Teaches the agent how to use those profiles safely.

It manages only its own block in ~/.aws/config. It never writes a [default] profile and never changes profiles you created yourself.

What the agent gets

Each identity you selected appears as an AWS CLI profile. The agent lists them with:

Terminal

alfe aws profiles

Output

PROFILE      ACCOUNT       ROLE                                       REGION     LABEL
production   123456789012  (direct)                                   us-east-1  Production
prod-deploy  123456789012  arn:aws:iam::123456789012:role/DeployRole  us-east-1

Add --json to get the same list as a JSON array.

The agent then names a profile on every AWS command:

Terminal

aws sts get-caller-identity --profile production
aws s3 ls --profile prod-deploy
aws ec2 describe-instances --profile production --region eu-west-1

There’s no default profile, so every command must pass --profile. Credentials are fetched and refreshed automatically; the agent never runs aws configure or handles keys.

Security model

Alfe keeps your long-lived secrets out of the agent’s reach:

• Keys never leave Alfe. Access keys, AWS SSO sign-ins, and shared sessions are stored encrypted and used only inside Alfe to issue temporary credentials. They’re never sent to an agent or shown in the dashboard.
• Agents get short-lived credentials. Role and access-key sessions last at most one hour. AWS SSO and shared-session credentials last as long as AWS issued them for; see How long credentials stay valid. The agent caches credentials on its host, readable only by its own user, and fetches new ones about every hour.
• Agents ask by profile, not by ARN. An agent can only request the profiles you selected on a connection in its scope.
• Every role session is attributable. Role and access-key sessions use the name alfe-<agentId>, so you can trace each agent’s activity in AWS CloudTrail. Calls Alfe makes during setup use alfe-setup. AWS SSO and shared sessions show your own identity instead.
• The external ID binds the role to your setup. Each setup link carries a new external ID. It works once and expires after 24 hours.

Revoke access

You can cut off access from Alfe or from AWS:

• In Alfe — select Disconnect on the connection, or untick a role in Manage roles. Alfe stops issuing credentials for it immediately.
• In AWS — delete the CloudFormation stack, or remove the Alfe principal from a role’s trust policy. For access keys, deactivate the key in IAM.
• For AWS SSO — disconnect the connection. Alfe also signs out the AWS SSO sign-in it held. Your AWS admin can end your IAM Identity Center session too.
• For a shared session — run alfe aws share with --stop, or disconnect it on the agent. See Share and stop a session.

Revoking in Alfe stops new credentials. Credentials an agent already holds keep working at AWS until they expire:

• Role and access-key connections — up to 1 hour.
• AWS SSO — up to the permission set’s session duration, from 1 to 12 hours.
• Shared session — until the session you shared expires, up to 12 hours.

Cut access immediately in AWS

To stop issued credentials right away, revoke them in AWS:

• Role, AWS SSO, or a shared role session — in the IAM console, use Revoke active sessions on the role. For AWS SSO, that’s the role AWS created for your permission set, named AWSReservedSSO_<PERMISSION_SET>_….
• AWS SSO user — this doesn’t stop credentials already issued, but in IAM Identity Center you can end the user’s active sessions and remove their account assignment so no new ones are issued. Pair it with Revoke active sessions on the role above.
• Access keys — deactivate the key in IAM.

Otherwise, access ends when the credentials expire.

Limitations

• Direct access-key profiles can’t call IAM APIs. An access-key Direct profile uses a temporary session token, and AWS blocks IAM API calls from those without MFA. Use a role profile for IAM work.
• Role sessions last at most one hour. AWS caps chained role sessions at one hour. Credentials refresh automatically, but a single long-running command can outlive its session.
• Commercial AWS partition only. Accounts and regions in AWS GovCloud (US) and AWS China aren’t supported.
• SSO and shared-session connections belong to one person. Only the person who connected can change their roles or sign in again, and they can’t move to another scope.
• Shared sessions cover one agent and one profile. To give several agents your access, use Sign in with AWS SSO instead.
• Add and manage from the dashboard or desktop app. The mobile app shows AWS connections but can’t add them or change their roles.

Troubleshooting

“Waiting for AWS…” doesn’t finish

The stack hasn’t finished creating the role. Open the stack in CloudFormation and wait for CREATE_COMPLETE, then select Try again.

Alfe can’t use the role

Check the account ID or role ARN you entered. Also check that you created the stack from the link Alfe gave you, because that link carries the matching external ID. If you edited the stack’s parameters, launch it again from Alfe.

The setup link expired or was already used

Setup links expire after 24 hours and work once:

• During setup — select Launch in AWS again for a fresh link, then update the stack with it.
• For an existing role connection — select Re-issue link on the connection. Alfe opens an Update stack link with a new external ID. When the stack shows UPDATE_COMPLETE, select I’ve updated the stack so Alfe can re-check access. An active connection stays active throughout.

Check the external ID on Update stack

AWS may not fill in the new external ID when you update a stack. Alfe shows the new value in a copy field next to the link. If the stack’s ExternalId parameter isn’t already set to it, paste it in before you update.

Alfe says the role doesn’t require the external ID

The role’s trust policy lets Alfe in without the external ID. Alfe refuses these roles, because anyone who learned the role ARN could reach your account through Alfe.

Update the trust policy to require sts:ExternalId, then try again. The CloudFormation template from Alfe already does this, so recreating the role from the setup link also fixes it.

Alfe says STS isn’t activated

AWS Security Token Service (STS) is turned off for your account in the region Alfe requests credentials from. In the IAM console, open Account settings and activate the inactive STS regional endpoints. Then try again.

Agents see the same message when they request credentials until STS is activated.

Alfe says there were too many attempts

Alfe limits how often AWS is called during setup and for each agent profile. The message tells you how long to wait. Wait that long, then try again.

Agents cache each session for up to an hour, so a healthy agent rarely hits the limit. If one does, look for a script that requests credentials in a tight loop.

The connection shows “Setup incomplete”

The account is verified, but no roles are saved yet, so agents can’t use it. Select Finish setup to choose roles, or disconnect it if you no longer need it.

The agent is denied when it requests credentials

AWS refused to issue a session for the profile, so the AWS command fails before it runs. The agent reports the reason. Common causes:

• The role, or its trust policy, was changed or deleted in AWS.
• A chained role no longer trusts the connected identity.
• STS isn’t activated in the region Alfe uses; see Alfe says STS isn’t activated.

For a role connection, select Re-issue link and run the update. That puts the Alfe role back to the shape Alfe expects. For a chained role, fix its trust policy in AWS.

The connection shows “Sign-in expired”

Your IAM Identity Center session ended, so agents can’t get credentials. If you made the connection, select Sign in again and approve the new code. Agents keep the same accounts and roles. Only the person who signed in sees Sign in again.

AWS can’t find the sign-in portal

Alfe asked the wrong region for your IAM Identity Center. Check the SSO region: it must match the sso_region value for your profile in ~/.aws/config, not the region your resources run in. Also check the access portal URL.

The shared session expired

Shared credentials last only as long as the session you exported. The connection shows Expired, and agents are told to share again. Run aws sso login and alfe aws share again on your computer. To avoid this, add --watch so the session refreshes while your local sign-in lasts.

A profile name is already in use

Another AWS connection on the same agent already uses that profile name, so Alfe won’t save it. Profile names must be unique on each agent:

• In the dashboard — edit the flagged profile names, then save again.
• With alfe aws share — pass a different name with --as <NAME>.

Another person already shares a session under this name

Someone else has shared their own AWS session with this agent under the same profile name. You can’t replace another person’s session. Share yours under a different name with --as <NAME>, or ask them to stop theirs with alfe aws share --stop.

alfe aws share asks you to confirm shared use

Other people can chat with the agent, so sharing needs your confirmation. In a terminal, answer y at the prompt. Without a terminal, re-run the command with --confirm-shared. Read When other people can use your access first.

alfe aws share says the AWS CLI is too old

alfe aws share needs AWS CLI v2.9 or later for aws configure export-credentials. Update the AWS CLI, then run the command again. Check your version with aws --version.

alfe aws share can’t export credentials

Your local AWS session has probably ended. Run aws sso login --profile <LOCAL_PROFILE>, then share again. If the command says the profile uses long-term access keys, use an SSO or role profile instead.

AWS returns AccessDenied

The profile’s role doesn’t allow that action. The agent reports which profile and which action was denied. To fix it, either:

• add the permission to the role’s policy in AWS, or
• connect a role with a broader access level and select it in Manage roles.

AWS rejects the access keys

Check the access key ID and secret, and that the key is still Active in IAM. Root account keys are never accepted; create an IAM user, or use the role method.

Related resources

• Connection scopes — choose who can use the connection.
• Providers & managing connections — label, move, or disconnect a connection.
• Managing integrations — install integrations on an agent.
• CLI overview — sign in with alfe login before you share a session.
• AWS IAM Identity Center User Guide — set up SSO users, permission sets, and session length.
• AWS CloudTrail User Guide — trace agent activity by session name.