# !aws.organization_id

The `!aws.organization_id` YAML function retrieves the AWS Organization ID
by calling the AWS Organizations `DescribeOrganization` API.

## Usage

The `!aws.organization_id` function takes no parameters:

```yaml
  # Get the AWS Organization ID
  org_id: !aws.organization_id
```

## Arguments

This function takes no arguments. It uses the AWS credentials from the environment or the
Atmos authentication context if configured.

## How It Works

When processing the `!aws.organization_id` YAML function, Atmos:

1. **Loads AWS Configuration** - Uses the standard AWS SDK credential resolution chain:
   - Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`)
   - Shared credentials file (`~/.aws/credentials`)
   - Shared config file (`~/.aws/config`)
   - EC2 Instance Metadata Service (IMDS)
   - ECS Task credentials
   - Web Identity Token credentials

2. **Calls Organizations DescribeOrganization** - Makes an API call to retrieve the organization details

3. **Returns Organization ID** - Extracts and returns the organization ID (e.g., `o-abc123def4`) as a string

## Authentication

### Atmos Auth Integration

When using [Atmos Authentication](/cli/commands/auth/usage), the function automatically uses credentials
from the active identity. This enables seamless integration with SSO, assume role chains, and other
authentication methods configured in your `atmos.yaml`.

The credential resolution order is:

1. **Atmos Auth Context** (highest priority) - If an identity is active (via `--identity` flag or
   default identity in `settings.auth`), Atmos uses the Atmos-managed credential files and profile
   instead of the standard AWS credential chain
2. **Standard AWS SDK resolution** (fallback) - If no Atmos auth context is available, falls back
   to the standard chain (environment variables, `~/.aws/credentials`, IMDS, etc.)

When Atmos Auth is active, the function receives an `AWSAuthContext` containing:

- **Profile** - The identity name (e.g., `core-auto/terraform`)
- **CredentialsFile** - Path to Atmos-managed credentials (e.g., `~/.atmos/auth/{realm}/aws/{provider}/credentials`)
- **ConfigFile** - Path to Atmos-managed config (e.g., `~/.atmos/auth/{realm}/aws/{provider}/config`)
- **Region** - AWS region from the identity or component override

This context is passed to `LoadConfigWithAuth()`, which configures the AWS SDK to use the Atmos-managed
files instead of the default `~/.aws/` paths.

### Stack-Level Auth Configuration

Auth can be configured at three levels, with component-level taking highest precedence:

**File:** `atmos.yaml`

```yaml
# Global auth configuration
auth:
  identities:
    core-auto/terraform:
      kind: aws/permission-set
      default: true
      via:
        provider: aws-sso
```

**File:** `stack.yaml`

```yaml
components:
  terraform:
    my-component:
      # Component-level auth override (highest precedence)
      settings:
        auth:
          identities:
            prod-deploy:
              default: true
              kind: aws/assume-role
      vars:
        # Uses credentials from prod-deploy identity
        organization_id: !aws.organization_id
```

### Using with the `--identity` Flag

```bash
# Explicitly specify the identity for the command
atmos terraform plan my-component -s prod-ue1 --identity core-auto/terraform

# The !aws.organization_id function will use the core-auto/terraform credentials
```

## Caching

The `!aws.organization_id` function uses its own cache, separate from the identity functions
(`!aws.account_id`, `!aws.caller_identity_arn`, etc.). Results are cached in memory for
the duration of the CLI invocation:

- Multiple uses of `!aws.organization_id` in the same command only make one Organizations API call
- Different authentication contexts (e.g., different profiles or credential files) get separate cache entries
- The cache key is derived from `Profile:CredentialsFile:ConfigFile`, so different identities never share cached results
- Each new CLI command starts with a fresh cache

:::note Type-Aware Merging
Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
:::

## Examples

### Basic Usage

**File:** `stack.yaml`

```yaml
components:
  terraform:
    my-component:
      vars:
        # Inject the AWS Organization ID into Terraform variables
        organization_id: !aws.organization_id
```

### Resource Tags

**File:** `stack.yaml`

```yaml
components:
  terraform:
    vpc:
      vars:
        tags:
          OrganizationId: !aws.organization_id
          AccountId: !aws.account_id
          ManagedBy: "atmos"
```

### SCP and Policy Scoping

**File:** `stack.yaml`

```yaml
components:
  terraform:
    scp-policies:
      vars:
        organization_id: !aws.organization_id
        account_id: !aws.account_id
```

### Cross-Account References

**File:** `stack.yaml`

```yaml
components:
  terraform:
    cross-account-role:
      vars:
        organization_id: !aws.organization_id
        trusted_org_id: !aws.organization_id
```

## Comparison with Terragrunt

This function is equivalent to Terragrunt's `get_aws_org_id()` function:

| Terragrunt | Atmos |
|------------|-------|
| `get_aws_org_id()` | `!aws.organization_id` |

## Error Handling

If the function fails to retrieve the AWS organization info, Atmos will log an error and exit.

Common error scenarios:

- **No AWS credentials configured** - Standard credential resolution fails
- **Account not in an organization** - The AWS account is not a member of an AWS Organization
- **Missing permissions** - The caller does not have the `organizations:DescribeOrganization` permission
- **Network connectivity issues** - Cannot reach the AWS Organizations endpoint

## Considerations

- **Requires `organizations:DescribeOrganization` permission** - This is a specific IAM permission
  that may not be available by default, unlike `sts:GetCallerIdentity`
- **Requires organization membership** - The AWS account must be a member of an AWS Organization.
  Standalone accounts will receive an error
- **Network dependency** - Requires connectivity to the AWS Organizations endpoint
- **Performance** - Results are cached per CLI invocation, so there's minimal overhead when used
  multiple times
- **Separate cache** - Uses a separate cache from the identity-based functions (`!aws.account_id`,
  `!aws.region`, etc.) since it calls a different AWS API

## Related Functions

- [!aws.account\_id](/functions/yaml/aws.account-id) - Get the AWS account ID
- [!aws.caller\_identity\_arn](/functions/yaml/aws.caller-identity-arn) - Get the full ARN of the caller identity
- [!aws.caller\_identity\_user\_id](/functions/yaml/aws.caller-identity-user-id) - Get the unique user ID
- [!aws.region](/functions/yaml/aws.region) - Get the AWS region