# Single account

> Connect one AWS account to LevelFour in a click from the dashboard, with a CloudFormation Launch Stack link, or with Terraform. Covers the two IAM roles the stack creates and how to revoke them.

Source: https://docs.levelfour.ai/connectors/aws/single-account


LevelFour reads your AWS costs through IAM roles it creates in your account. You can connect one account from the dashboard in a click, with a CloudFormation Launch Stack link where you enter the handshake ID LevelFour gave you, or with Terraform.

If your accounts sit under AWS Organizations, the [multi-account path](/connectors/aws/multi-account) onboards every one of them in a single deployment.

## Self-service path (recommended)

The whole flow runs from the LevelFour dashboard without an onboarding contact in the loop. Go to **Connect Providers > AWS** in the dashboard (`https://dashboard.levelfour.ai/connect-accounts/aws`) and click **Connect via AWS Console**. The dashboard opens AWS Console with the v2 CloudFormation template pre-loaded. Click **Create stack**, and the deployed stack pings LevelFour automatically.

> **Success**
>
> The dashboard flips to **Connected** within ~30 seconds and starts ingesting cost data for that account. Nothing to send back to LevelFour, and no ARNs to copy.

## Prerequisites

* An AWS account with permission to create IAM roles and CloudFormation stacks (typically an admin role)
* The **LevelFour Handshake ID** provided by your LevelFour contact

## Deploy with a Launch Stack link

Use the steps below when you cannot reach the dashboard, for example when the person who holds AWS access is not the LevelFour admin.

### Open the Launch Stack link

Sign in to the AWS account you want to onboard, then click the Launch Stack link below. It opens the CloudFormation console with the LevelFour onboarding template pre-loaded.

```text
https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://cf-templates-1bsphth8u70q9-us-east-1.s3.amazonaws.com/onboarding/v2/onboarding-levelfour-cloudformation-template.json&stackName=LevelFour
```

Region does not matter for IAM resources. Leave it on `us-east-1`.

> **Warning**
>
> CloudFormation deploys into whichever account the console is signed in to. Check the top-right account selector before you create the stack. A stack in the wrong account creates a role there that trusts LevelFour, and undoing it means deleting that stack.

### Enter the handshake ID

CloudFormation shows the template's parameters:

* **LevelFourHandshakeID**: paste the value LevelFour gave you. Treat it like a secret, and do not share or change it.
* **IntegrationID** and **PingbackTopicArn**: leave both blank. Only the dashboard self-service flow uses them, to auto-confirm the connection.

Leave the stack name as `LevelFour`, or change it if your team uses a naming convention.

> **Warning**
>
> A handshake ID that does not match still deploys cleanly. The stack reaches `CREATE_COMPLETE` and the connection never works. Paste the value, do not retype it.

### Acknowledge the IAM capability

At the bottom of the page, tick:

> I acknowledge that AWS CloudFormation might create IAM resources with custom names.

AWS asks for this because the template creates roles with specific names (`LevelFourCrossAccountRole`, plus an empty `LevelFourSavingsExec` role for Automated Savings) rather than letting AWS auto-generate them. Predictable names let LevelFour find the roles without you copying ARNs back to LevelFour.

Click **Create stack**.

### Wait for `CREATE_COMPLETE`

CloudFormation provisions the role. It typically takes 30 to 60 seconds. Watch the **Events** tab for progress.

> **Success**
>
> When the stack status reaches `CREATE_COMPLETE`, the role exists in your account. Whether LevelFour can use it is confirmed in the next step, not here.

### Confirm the role and notify LevelFour

Open the stack's **Outputs** tab:

* **RoleArn**: `arn:aws:iam::<your-account-id>:role/LevelFourCrossAccountRole`
* **SavingsExecRoleArn**: `arn:aws:iam::<your-account-id>:role/LevelFourSavingsExec` (the Automated Savings execution role)
* **HandshakeID**: the same value you entered, echoed back for verification

Reply to your LevelFour contact with the AWS account ID. LevelFour validates that the role works (it attempts an `sts:AssumeRole` using your handshake ID) and starts ingesting data for that account.

## Deploy with Terraform

Use this path when you manage the account as code. Terraform deploys the same LevelFour template through an `aws_cloudformation_stack` resource. The roles and their permissions match the Launch Stack link, and the stack lives in your Terraform state.

### Add the stack to your configuration

Point the AWS provider at the account you want to onboard. `allowed_account_ids` stops Terraform before it changes anything in a different account. If your configuration already has a provider for this account, keep yours and leave this one out.

```hcl title="levelfour.tf"
provider "aws" {
  region              = "us-east-1"
  allowed_account_ids = ["<your-account-id>"]
}

variable "levelfour_handshake_id" {
  description = "The handshake ID LevelFour gave you"
  type        = string
  sensitive   = true
}

resource "aws_cloudformation_stack" "levelfour" {
  name         = "LevelFour"
  template_url = "https://cf-templates-1bsphth8u70q9-us-east-1.s3.amazonaws.com/onboarding/v2/onboarding-levelfour-cloudformation-template.json"
  capabilities = ["CAPABILITY_NAMED_IAM"]

  parameters = {
    LevelFourHandshakeID = var.levelfour_handshake_id
  }
}

output "levelfour_role_arn" {
  value = aws_cloudformation_stack.levelfour.outputs["RoleArn"]
}

output "levelfour_savings_exec_role_arn" {
  value = aws_cloudformation_stack.levelfour.outputs["SavingsExecRoleArn"]
}
```

`CAPABILITY_NAMED_IAM` is the acknowledgement the console asks for, because the template creates `LevelFourCrossAccountRole` and `LevelFourSavingsExec` by name. Leave `IntegrationID` and `PingbackTopicArn` out. Only the dashboard flow uses them.

### Apply with your handshake ID

Pass the handshake ID through an environment variable, so it stays out of your `.tf` and `.tfvars` files:

```bash
export TF_VAR_levelfour_handshake_id='<your-handshake-id>'
terraform init
terraform apply
```

`terraform apply` returns once the stack reaches `CREATE_COMPLETE`, typically 30 to 60 seconds later. If CloudFormation rolls the stack back, the apply fails and prints the stack's error.

> **Warning**
>
> A handshake ID that does not match still deploys cleanly. The apply succeeds and the connection never works. Paste the value, do not retype it.

### Check the outputs and notify LevelFour

Run `terraform output` to see both role ARNs:

* **levelfour\_role\_arn**: `arn:aws:iam::<your-account-id>:role/LevelFourCrossAccountRole`
* **levelfour\_savings\_exec\_role\_arn**: `arn:aws:iam::<your-account-id>:role/LevelFourSavingsExec` (the Automated Savings execution role)

Reply to your LevelFour contact with the AWS account ID. LevelFour validates that the role works (it attempts an `sts:AssumeRole` using your handshake ID) and starts ingesting data for that account.

## Onboarding more accounts

Repeat the deploy in each additional AWS account, using the same handshake ID. Each account gets its own role with the same predictable name. With Terraform, that is one `aws_cloudformation_stack` per account, each under a provider for that account.

Past three or four accounts, switch to the [multi-account path](/connectors/aws/multi-account).

## What the stack creates

The stack creates two roles. Both trust LevelFour's AWS account (`730335248431`) and only accept AssumeRole requests that include your specific `LevelFourHandshakeID` as the external ID.

`LevelFourCrossAccountRole` is the read-only role LevelFour uses to analyze your costs. Its permissions:

* AWS managed `ReadOnlyAccess` (read-only access to all resources)
* A focused inline policy covering: Cost Explorer, Compute Optimizer, Cost Optimization Hub, Savings Plans, Pricing, AWS Support, Trusted Advisor, S3 Storage Lens, BCM Data Exports, Container Insights, and the IAM service-linked role creation needed to enroll in those services

`LevelFourSavingsExec` is created empty, with no attached permissions. It exists so that, when you approve a specific [Automated Savings](/connectors/aws/automated-savings) action, a scoped policy covering only that action and its resources is attached for a short, time-limited window and then expires on its own. Nothing in your account can be changed until you explicitly approve such an action.

You can review the full template before deploying:

```text
https://cf-templates-1bsphth8u70q9-us-east-1.s3.amazonaws.com/onboarding/v2/onboarding-levelfour-cloudformation-template.json
```

## Removing access

To revoke LevelFour's access to an account, delete the CloudFormation stack:

```bash
aws cloudformation delete-stack --stack-name LevelFour
```

This removes both roles (`LevelFourCrossAccountRole` and `LevelFourSavingsExec`). LevelFour stops being able to read data from that account immediately.

If you deployed with Terraform, remove the `aws_cloudformation_stack.levelfour` resource and its two outputs from your configuration, then run `terraform apply`. Do not delete the stack with the AWS CLI instead: the resource is still in your configuration, so the next `terraform apply` creates the stack again.

## Troubleshooting

| Symptom                                                                       | Cause                                                                                     | Fix                                                                                                                                                 |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CREATE_FAILED`, "Role with name LevelFourCrossAccountRole already exists"    | The LevelFour role is already deployed in this account                                    | Skip it, the account is already onboarded. To redeploy, delete the existing role first                                                              |
| `CREATE_FAILED` with an SCP-related error                                     | Service Control Policies in your AWS Organization block IAM role creation in this account | Ask your AWS administrator to permit `iam:CreateRole`, `iam:AttachRolePolicy` and `iam:PutRolePolicy` for the role name `LevelFourCrossAccountRole` |
| `terraform apply` fails with `Requires capabilities : [CAPABILITY_NAMED_IAM]` | The `aws_cloudformation_stack` resource has no `capabilities` argument                    | Add `capabilities = ["CAPABILITY_NAMED_IAM"]` and apply again                                                                                       |
| The stack succeeded but LevelFour says the role is not accessible             | The handshake ID you entered does not match what LevelFour provided                       | Update the stack and re-enter the correct value. With Terraform, export the correct `TF_VAR_levelfour_handshake_id` and apply again                 |

## Next

* [Detailed cost data](/connectors/aws/detailed-cost-data) turns on the Cost and Usage Report, which is what gives you resource-level and tag-level breakdowns
* [Automated Savings](/connectors/aws/automated-savings) covers the `LevelFourSavingsExec` role, including accounts onboarded before it existed