Connecting an AWS account

Connecting AWS is real in Cushy. Access is read-only and uses a cross-account IAM role assumed with STS — there are no long-lived access keys to create, store or rotate.

How the trust works

You create an IAM role in your AWS account that trusts Cushy's AWS account, scoped by an `ExternalId` unique to your connection (the confused-deputy defense). Cushy assumes that role with STS and makes SigV4-signed, read-only calls to discover inventory. It never holds your credentials — only the ability to assume a role you control and can revoke at any time.

Connect

1. 1
   Start a connection

   On Cloud accounts (/clouds), choose AWS. This creates the connection record and gives you the trust details (Cushy's account id and your ExternalId).

2. 2
   Create the role

   Use the provided CloudFormation quick-create link to provision the read-only role with the correct trust policy and ExternalId in one click, or create it manually from the shown policy.

3. 3
   Verify

   Click Verify connection (`POST /api/cloud/accounts/{id}/validate`). Cushy assumes the role and runs health checks. On success the status becomes healthy, the empty-to-real cutover fires, and a first sync starts within seconds.

Health checks and missing permissions

Verification runs concrete checks and reports each one. If a permission is missing, the response carries the exact missing permissions (a 409 with a missing array) so you can fix the policy precisely — nothing is partially synced for an unhealthy account. A transient provider error surfaces as a 503 you can retry.

Advanced connection parameters

Everything a real connection needs is captured on the connect form — open Advanced / real connection under the connect card to set them. All are optional with sensible defaults shown inline; they are stored in the connection's encrypted payload and drive the real adapter.

Cushy's trust anchors

The connect instructions render the real Cushy AWS account id your role must trust — anyone in your organization who can manage cloud accounts sees the resolved value inline, and the CloudFormation link is pre-filled with it. Onboarding never asks you to look a value up elsewhere.

Duplicate detection and disconnect

Connecting an AWS account that is already connected returns a 409 with the existing connection's id. To disconnect, `DELETE /api/cloud/accounts/{id}` marks the connection disconnected and its discovered rows account_disconnected — nothing is purged. Cushy's access was read-only, so the reminder is to delete the IAM role in your AWS account to fully de-provision.