> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Account API: Connect and Verify AWS Access

> REST endpoints to inspect the AWS account connected to your organization and verify that Springwinter can assume the required IAM role.

The AWS Account API lets you inspect the AWS account connected to your Springwinter organization and verify that the IAM role Springwinter uses is correctly configured. Springwinter never stores permanent AWS credentials — instead, it assumes a single IAM role in your account on each API call, scoped to the minimum permissions required. Use these endpoints to confirm the connection details and trigger a live verification check.

## How the Connection Works

When you connect an AWS account, Springwinter guides you through launching a CloudFormation stack. The stack creates one IAM role with a trust policy that allows only Springwinter's principal to assume it — and only when the correct external ID is presented. Springwinter never stores long-lived AWS access keys; every operation uses a fresh set of temporary credentials obtained by calling `sts:AssumeRole` at request time.

<CardGroup cols={2}>
  <Card title="One role, least privilege" icon="shield-check">
    The CloudFormation-managed role includes only the permissions Springwinter needs to deploy and manage your resources. No IAM administrator access is granted.
  </Card>

  <Card title="No stored credentials" icon="key">
    Springwinter calls `sts:AssumeRole` on each operation and discards the credentials when the call completes. There are no long-lived access keys to rotate or leak.
  </Card>
</CardGroup>

***

## Get AWS Account Details

**GET /api/aws\_account**

Return the AWS account ID, role name, and connection status for the account linked to your organization.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/aws_account \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "account_id": "123456789012",
    "role_name": "SpringwinterRole",
    "external_id": "sw-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "active": true,
    "connected_at": "2025-01-08T16:20:00Z"
  }
  ```
</CodeGroup>

<ResponseField name="account_id" type="string">
  The twelve-digit AWS account ID of the connected account.
</ResponseField>

<ResponseField name="role_name" type="string">
  The name of the IAM role Springwinter assumes. This role was created by the CloudFormation stack you launched during the AWS connection flow.
</ResponseField>

<ResponseField name="external_id" type="string">
  The unique external ID embedded in the AssumeRole trust policy. Springwinter generates this value when you start the Connect AWS flow to prevent confused deputy attacks.
</ResponseField>

<ResponseField name="active" type="boolean">
  `true` if the last verification of the role succeeded. `false` if the role cannot currently be assumed — for example, because the trust policy was modified or the role was deleted.
</ResponseField>

<ResponseField name="connected_at" type="string">
  ISO 8601 timestamp of when the AWS account was first connected.
</ResponseField>

***

## Verify the AWS Connection

**POST /api/aws\_account/verification**

Perform a live AssumeRole call to confirm that Springwinter can still access your AWS account with the configured role. If the call succeeds, the connection is marked active and the result is persisted. If it fails, the endpoint returns `422 Unprocessable Entity` with a description of the error.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/aws_account/verification \
    -H "Authorization: Bearer swt_yourtoken" \
    -H "Content-Type: application/json" \
    -d '{
      "account_id": "123456789012",
      "role_name": "SpringwinterRole",
      "external_id": "sw-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }'
  ```

  ```json Response (200 OK) theme={null}
  {
    "verified": true,
    "account_id": "123456789012",
    "role_arn": "arn:aws:iam::123456789012:role/SpringwinterRole"
  }
  ```
</CodeGroup>

<ParamField body="account_id" type="string" required>
  The AWS account ID to verify. Must match the account where the CloudFormation stack was deployed.
</ParamField>

<ParamField body="role_name" type="string" required>
  The name of the IAM role to assume. The role must exist in the specified account and have a trust policy that allows Springwinter's principal to assume it with the given external ID.
</ParamField>

<ParamField body="external_id" type="string" required>
  The external ID generated by Springwinter for your organization's connection. Retrieve it from the `GET /api/aws_account` response or from the Connect AWS flow in the dashboard.
</ParamField>

<ResponseField name="verified" type="boolean">
  `true` when the AssumeRole call succeeded and the connection has been marked active.
</ResponseField>

<ResponseField name="account_id" type="string">
  The AWS account ID that was verified.
</ResponseField>

<ResponseField name="role_arn" type="string">
  The full ARN of the IAM role that was successfully assumed.
</ResponseField>

### Verification Failure

If Springwinter cannot assume the role, the endpoint returns `422 Unprocessable Entity` with a description of the failure.

```json Response (422 Unprocessable Entity) theme={null}
{
  "verified": false,
  "error": "AccessDenied",
  "message": "The role trust policy does not permit Springwinter to assume this role. Ensure the Principal and Condition match the values in the CloudFormation template."
}
```

<Warning>
  If verification fails after a previously successful connection, check that the IAM role's trust policy and permissions boundary have not been modified. Re-deploying the Springwinter CloudFormation stack will reset the role to the required configuration.
</Warning>

***

<Note>
  The external ID is unique per organization and is generated once when you start the Connect AWS flow in the Springwinter dashboard. It is baked into the CloudFormation template so the trust policy is configured correctly from the start. Never share your external ID publicly — it is part of the security model that prevents third parties from tricking Springwinter into assuming your role.
</Note>