Automate AWS GovCloud (US) account creation using AWS Organizations APIs

AWS GovCloud (US) is an innovative cloud solution that includes a pair of AWS Regions providing a cloud computing environment designed specifically for government agencies, contractors, and organizations that handle sensitive, International Traffic in Arms Regulations (ITAR)-controlled data and require US citizenship or entity status. AWS GovCloud (US) regions exist as a separate partition from commercial AWS regions. This post explains the GovCloud account creation process and how to automate it.

Automating GovCloud account creation helps government agencies and contractors reduce manual overhead when implementing multi-account strategies, provides consistent security posture across accounts, and accelerates time-to-value for mission-critical workloads. By automating repeatable tasks, your team can focus on delivering value to citizens rather than managing account provisioning.

Although there are a lot of account management APIs available, the process of creating a GovCloud account using APIs has certain requirements, and some of that cannot be automated or the tasks need to be performed only one time. Because it’s inefficient to spend the time to automate one-time tasks, we break down what the tasks are and automate the repeatable tasks. To keep the post short, we’ll refer the tasks to other documentation wherever possible.

Prerequisites

To perform the solution, you need to have the following prerequisites:

• A standard AWS account in the commercial partition.
• Credentials to sign in as root user.
• AWS CommandLine Interface (CLI) installed and configured.

Create an organization in the commercial partition

To create a GovCloud account via the API, you must first set up an organization in a standard account using AWS Organizations. Creating an organization is a one-time task and doesn’t need to be automated. If you already have an organization created, you can skip to Create a GovCloud (US) account from your management account in commercial partition. To create an organization, follow these steps:

1. Designate a standard account to be a management account.
2. Sign in to the account as root user using email and password, and create an organization.

The standard account must be a standalone account – this is also known as the “commercial account”. It cannot be a member account of an organization. After an organization has been created, this standalone account will become the organization’s management account.

Create a GovCloud (US) account from your management account in commercial partition

Create a GovCloud account from organization’s management account is also a one-time task and must be carried out in the commercial partition. By requesting GovCloud account that paired with the management account in commercial partition, you unlock the ability to spin up additional GovCloud accounts via automation. If you already have a GovCloud account paired with the management account in the commercial partition, you can skip to Use APIs to create GovCloud account(s). For more in-depth instructions to create a GovCloud account manually, visit AWS GovCloud (US) Sign Up in the AWS GovCloud (US) User Guide. Follow these steps:

1. Sign in to the management account as root user using email and password.
2. In the upper right-hand corner, choose the down arrow.
3. Choose Account
4. Scroll down to the Other settings section
5. Choose To sign up for AWS GovCloud (US), see AWS GovCloud.
6. Follow the on-screen instructions to create the GovCloud account.

If you don’t see the link to sign up for a GovCloud account, then you did not sign in as the root user. If you run into an error during step 5, take one of the following actions:

• If you’re working with an account manager, solutions architect, or Technical Account Manager (TAM), seek their assistance.
• If you’re working with an AWS Partner or solution provider, open a ticket with them for assistance.
• Open a support case with AWS Support requesting assistance to create the GovCloud account. Be sure to select Account and billing issue, set Service to Account and Category to AWS GovCloud (US) – Onboarding.

Use APIs to create GovCloud account(s)

The steps in this section show you how to automate the process of creating new GovCloud accounts. Call AWS Organizations APIs to create a GovCloud account and retrieve the account IDs. Follow these steps:

1. Configure AWS CLI using access key and secret key of an AWS Identity and Access Management (IAM) user from the organization’s management account in commercial partition.
2. Call CreateGovCloudAccount to create a new GovCloud account.
3. Capture the car-xxxx id and wait a few minutes for the accounts to be created.
4. Call DescribeCreateAccountStatus with car-id to retrieve the 2 new account IDs.
5. If you didn’t catch the car-xxxx id, you can also use ListCreateAccountStatus to get new account IDs.

If using access or secret keys isn’t feasible, you could use an IAM role or an Amazon Elastic Compute Cloud (Amazon EC2) instance profile and execute the APIs using AWS CloudShell, EC2 instance, or AWS Lambda function. This process will create a new standard account paired with a new GovCloud account.

Here’s the Lambda function that automates GovCloud account creation (Python):

import json
import boto3
import time

org_client = boto3.client('organizations')

def lambda_handler(event, context):
    """
    Creates GovCloud account and returns both commercial & GC account IDs after status check
    
    Expected event format:
    {
        "email": "govcloud@company.com",
        "account_name": "Production-GovCloud"
    }
    """
    
    try:

        # Step 1: Extract parameters from event
        email = event['email']
        account_name = event['account_name']
        
        # Step 2: Create GovCloud account
        response = org_client.create_gov_cloud_account(
            Email=email,
            AccountName=account_name
        )
        request_id = response['CreateAccountStatus']['Id']
        print(f'Car-id: {request_id}')
        
        # Step 3: Check account creation status
        max_attempts = 20
        attempts = 0
        while attempts < max_attempts:
                
            # Wait 10 seconds for the account to be created
            time.sleep(10)

            status_response = org_client.describe_create_account_status(
                CreateAccountRequestId=request_id
            )
            create_status = status_response['CreateAccountStatus']

            if create_status['State'] != 'IN_PROGRESS':
                break
            attempts += 1
        
        result = json.dumps({
                'request_id': request_id,
                'state': create_status['State'],
                'commercial_account_id': create_status.get('AccountId'),
                'govcloud_account_id': create_status.get('GovCloudAccountId'),
                'failure_reason': create_status.get('FailureReason')
            })
        print(result)

        return {
            'statusCode': 200,
            'body': result
        }
        
    except Exception as e:
        return {
            'statusCode': 500,
            'body': json.dumps({
                'error': str(e)
            })
        }

When you execute the Lambda function, you need to pass in an event payload that contains an email address and a name for the new account. The email address will be associated with the standard account. It must be unique and previously unused to create an AWS account. Here’s the event format you need to pass to the Lambda function:

{
    "email": "example@company.com",
    "account_name": "name for your account"
}

The Lambda execution role requires this IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CreateGovCloudAccountPermissions",
            "Effect": "Allow",
            "Action": [
                "organizations:CreateGovCloudAccount",
                "organizations:DescribeCreateAccountStatus"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CloudWatchLogsPermissions",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

And this is the associated trust policy for the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

When you execute the Lambda function, it should return a message like the following example.

{
    "request_id": "car-1fb333bf1...",
    "state": "SUCCEEDED",
    "commercial_account_id": "111222333444",
    "govcloud_account_id": "555666777888",
    "failure_reason": null
}

Parse the response and retrieve the account IDs and proceed to Assume role into the new accounts and perform additional configurations.

Creating a new GovCloud account programmatically should take less than 2 minutes to complete under normal circumstances. In our tests, the accounts were created in under 75 seconds. Make sure the Lambda function timeout property is set long enough for the process to complete. You can also break out step 3 into a different function. After you obtain the account IDs, you will want to store them according to your organization’s security standards. If the Lambda function times out, check the Amazon CloudWatch logs and use the request ID to call DescribeCreateAccountStatus to retrieve the account IDs. For each set of accounts that you create, AWS will send 2 welcome emails to the specified email address you used to create the accounts.

Assume role into the new accounts and perform additional configurations

When new accounts (both standard & GovCloud) are created by API, only a role is created in the new accounts; no password is generated. To access the new accounts, you must sign in to the management accounts and assume role into the newly created accounts in their respective partition. Once you have access to the new accounts, perform additional configurations.

The post account creation process is optional, and you can automate, or execute it manually using the AWS Management Console. We recommend that you do this to both commercial and GovCloud partitions. Follow these steps:

1. Sign in to the organization management account.
2. Switch role into the new account using the OrganizationAccountAccessRole role.
3. Check and update the AWS CloudTrail configuration. This is optional for the standard account.
4. Invite the new account to the organization for the GovCloud partition only.
5. Perform additional configuration for the account as required by your security best practices.

CloudTrail for the GovCloud account is automatically configured in the AWS GovCloud (US-West) us-gov-west-1 Region. Check and make configuration changes as required by your business needs. The new standard account will automatically join the organization in the commercial partition, and the new GovCloud account will remain a standalone account. If you have AWS Organizations set up in the GovCloud partition, you need to invite the new GovCloud account to join the organization.

Conclusion

In this post, we discussed how to automate AWS GovCloud (US) account creation using AWS Organizations APIs. By automating repeatable tasks and handling one-time setup manually, you can provision new GovCloud accounts in under 2 minutes—reducing manual effort and maintaining consistency across your multi-account environment. This automation helps your team scale securely while maintaining the compliance standards required for sensitive government workloads.

The Lambda function and IAM policies provided serve as building blocks you can extend to store account IDs securely and perform initial configurations according to your organization’s security requirements.

To learn more and get started, contact your AWS account team or the AWS Public Sector team.