Connect AWS

Zaysa connects to AWS without an access key. You create one IAM role in your account that trusts Zaysa. Each time Zaysa needs to read the account, it proves who it is with a token that lasts a few minutes, and AWS gives it temporary credentials for that role. Nothing long-lived is stored, and deleting the role ends the access.

Choose how to connect

Before you start

• A Zaysa account. New here? Start with Getting started.
• You can sign in to the AWS console of the account you want to connect, with permission to create an IAM OpenID Connect identity provider, create an IAM role and attach a policy to it.
• AWS CloudShell, which opens from the AWS console. You can also follow the same steps by hand in the IAM console.

What Zaysa gets

See the Permissions reference for each feature's exact grants and what happens without them. The default connection policy is ReadOnlyAccess.

Connect with keyless access

Option A: Cloud Shell script

1. Open the connection window

   In Zaysa, open Resources → Cloud Accounts and click Connect account (1).

   

2. Choose AWS and name the account

   (1) Keep Amazon Web Services as the provider. (2) Give the account a name you will recognise, for example Production. (3) Leave Keyless selected as the authentication method. All Regions is the right choice for most accounts.

   

3. Run the script in AWS CloudShell

   Scroll to Run this once in AWS CloudShell. Click Open CloudShell (1) and sign in to the AWS account you want to connect. Back in Zaysa, click Copy (2), paste the whole block into CloudShell and press Enter.

   

   The script is made for your account: it already contains your Zaysa user in the trust rule, so there is nothing to edit. It takes about 20 seconds and ends like this:

   AWS CloudShell

   → Setting up keyless access for AWS account 111122223333…
   
   ✅ Done! Paste this Role ARN into Zaysa:
      arn:aws:iam::111122223333:role/ZaysaDeploy

   Prefer the console?

   Choose Console, click by click instead of Cloud Shell script in the same window. It lists each IAM console screen in order, with every value ready to copy.

4. Paste the Role ARN

   Copy the ARN the script printed and paste it into IAM Role ARN (1). Zaysa checks the format and says Ready.

   

5. Click Connect Account

   Scroll to the bottom of the window and click Connect Account (1). Zaysa checks that AWS accepts its token for the role. The AWS Cost and Usage Report section above the button is optional: it adds the costs exactly as AWS invoices them, and you can set it up later.

   

   Asked to sign in again?

   Connecting a cloud account is a sensitive action. If you signed in more than 30 minutes ago, Zaysa asks you to sign in again with your email and password (and your authenticator code, if you use one), then brings you back to Cloud accounts. Open Connect account again and repeat the last two steps: the role in AWS is already there.

Option B: Console, click by click

Choose Console, click by click (1) in Zaysa. It gives you the exact trust policy after you enter your role ARN.

1. Add the identity provider

   Open IAM → Identity providers → Add provider. Set Provider type to OpenID Connect, Provider URL to https://zaysa.io, and Audience to sts.amazonaws.com. Click Add provider.

2. Create the role

   Open IAM → Roles → Create role. Choose Trusted entity type → Web identity, Identity provider → zaysa.io, and Audience → sts.amazonaws.com. Click Next. Under Permissions policies, search and tick ReadOnlyAccess. Click Next. Set Role name to ZaysaDeploy and click Create role.

3. Set the exact trust policy

   Open the role and copy its ARN to IAM Role ARN in Zaysa. Copy the trust policy that appears. Back in IAM, open Trust relationships → Edit trust policy, replace everything with the generated policy, and click Update policy. Click Connect Account in Zaysa.

Beam also needs

For just-in-time human access, Beam must be able to assume the role it mints from. The role needs iam:GetRole and iam:PutRolePolicy on itself to revoke issued sessions. Any explicit Deny must exempt Beam's revoke session. Beam › Connections › Check readiness checks each requirement and gives the exact fix.

Connect with access keys

Choose Access Keys / Secret (1) when keyless is unavailable. Zaysa stores the credentials encrypted. They are long-lived, do not expire on their own, and carry standing secret risk. Rotate them in IAM.

Option A: Cloud Shell script

1. Create the IAM user and key

   In Zaysa, click Copy on the access keys guide. Open AWS CloudShell in your account, paste the block, and press Enter. It creates or reuses IAM user Zaysa-Reader, attaches AWS managed ReadOnlyAccess, and creates one key. AWS allows two keys per user; the script stops when two exist.

   AWS CloudShell

   → Creating read-only access keys in AWS account 111122223333…
   
   ✅ Done! Paste these into Zaysa:
      Access Key ID:     AKIA••••••••••••
      Secret Access Key: ••••••••

2. Paste and test the key

   Paste Access Key ID (1) and Secret Access Key (2). Click Test Connection. The successful result is Successfully connected to AWS. Click Connect Account (1). A new key can take a few seconds to activate.

   

   

Option B: IAM console

1. Create the user

   Open IAM → Users → Create user. Under Specify user details, set User name to Zaysa-Reader. Leave Provide user access to the AWS Management Console unticked. Click Next. Under Set permissions, choose Permissions options → Attach policies directly. Search Permissions policies for ReadOnlyAccess, tick it, click Next and Create user.

2. Create the access key

   Open the user, then Security credentials → Access keys → Create access key. On Access key best practices & alternatives, choose Other and click Next. Set description tag is optional. Click Create access key. On Retrieve access key, click Show and copy Access key and Secret access key. The secret appears only now. Click Done, then paste both values in Zaysa.

The connected account card shows Key-based (1).

Rotate a key

In Zaysa, go to FinOps → Optimization. Under Connected cloud accounts, open the account's ⋮ menu and click Edit account & billing (1). Paste the new key and click Save Credentials. Then remove the old key in IAM.

Add the billing export (optional)

An AWS Cost and Usage Report gives Zaysa real invoiced cost.

Option A: Cloud Shell script

1. Fill the fields before copying

   Set Cost and Usage Report Name to zaysa-cur, S3 Region to your bucket region, and S3 path prefix to zaysa. Leave S3 Bucket Name empty until the script prints it. The Zaysa script uses these field values.

2. Create the report

   Click Copy in the billing guide. Open AWS CloudShell in the connected account, paste, and press Enter. The script creates bucket zaysa-cur-<account id> if missing, lets billingreports.amazonaws.com write through its bucket policy, and creates report zaysa-cur with hourly CSV and gzip, resource IDs, and prefix zaysa.

   AWS CloudShell

   ✅ Done! AWS will deliver the first files within 24 hours to:
      s3://zaysa-cur-111122223333/zaysa/zaysa-cur/
   Type this into Zaysa → S3 Bucket Name:  zaysa-cur-111122223333
   then click Save & Continue.

Option B: Billing console

1. Create a legacy CUR export

   Open Billing and Cost Management → Data Exports and click Create. Choose Export type → Legacy CUR export; Export name → zaysa-cur; Additional export content → Include resource IDs; Time granularity → Hourly; Report versioning → Overwrite existing report; Compression type and file format → gzip – text/csv.

2. Set the bucket and finish

   Under S3 bucket, click Configure, select or create the bucket and accept the bucket policy. Set S3 path prefix to zaysa, then click Create report. The guide also accepts Standard data export (CUR 2.0) with CSV, gzip, and resource IDs.

Save and test

Enter the exact Cost and Usage Report Name, S3 Bucket Name, S3 Region, and S3 path prefix. While connecting, click Save & Continue or Skip for now. For an existing account, use Edit account & billing and click Save Billing Config. Zaysa uses the connected identity with ReadOnlyAccess to read the bucket, with no extra permission.

Test checks whether Zaysa can read the report. Before the first file arrives, it says:

AWS CUR: no report files yet under s3://zaysa-cur-111122223333/zaysa/zaysa-cur/. A new report takes up to 24 hours to deliver its first file — try again later. If the report is older than that, check that the bucket, S3 path prefix and report name here match the report in AWS exactly.

Check it worked

Click Check permissions on the card to see which features are ready in this connection; the Check permissions guide explains the results.

The account appears on the Cloud accounts page with Keyless and Connected (1), the region and the AWS account number.

Run scan on the card takes you to the Cost Optimizer, where you scan the account to see what it costs and where the waste is. The first scan guide walks through it.

If something goes wrong

“Not signed in to AWS in this shell”

The script could not find an AWS identity. Open CloudShell from the AWS console of the account you want to connect, then paste the block again.

Zaysa says AWS rejected its token

• A new trust can take up to a minute to reach every AWS region. Wait a minute and click Verify again.
• Check that the ARN you pasted is from the same account where you ran the script.
• Each Zaysa user has their own trust rule. If a teammate ran the script, run it again while signed in to Zaysa as yourself: it adds your rule next to theirs.

“already has 2 access keys”

In IAM, open Zaysa-Reader → Security credentials. Delete an unused key and run the script again.

“no report files yet”

Wait up to 24 hours for the first file. For an older report, check the bucket, path prefix, and report name against AWS.

Remove access

To stop Zaysa reading the account, delete the ZaysaDeploy role in the IAM console, or only the trust statement that names Zaysa if other tools use the role. You can also delete the zaysa.io identity provider if nothing else uses it. For an access-key connection, delete its keys or the Zaysa-Reader IAM user. To remove the account from Zaysa, click the bin icon on its card.

Next steps