2026/03/31 - AWS Organizations - 8 updated api methods
Changes Added Path field to Account and OrganizationalUnit objects in AWS Organizations API responses.
{'OrganizationalUnit': {'Path': 'string'}}
Creates an organizational unit (OU) within a root or parent OU. An OU is a container for accounts that enables you to organize your accounts to apply policies according to your business requirements. The number of levels deep that you can nest OUs is dependent upon the policy types enabled for that root. For service control policies, the limit is five.
For more information about OUs, see Managing organizational units (OUs) in the Organizations User Guide.
If the request includes tags, then the requester must have the organizations:TagResource permission.
You can only call this operation from the management account.
See also: AWS API Documentation
Request Syntax
client.create_organizational_unit(
ParentId='string',
Name='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
ID for the parent root or OU that you want to create the new OU in.
The regex pattern for a parent ID string requires one of the following:
Root - A string that begins with "r-" followed by from 4 to 32 lowercase letters or digits.
Organizational unit (OU) - A string that begins with "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that the OU is in). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
string
[REQUIRED]
The friendly name to assign to the new OU.
list
A list of tags that you want to attach to the newly created OU. For each tag in the list, you must specify both a tag key and a value. You can set the value to an empty string, but you can't set it to null. For more information about tagging, see Tagging Organizations resources in the Organizations User Guide.
(dict) --
A custom key-value pair associated with a resource within your organization.
You can attach tags to any of the following organization resources.
Amazon Web Services account
Organizational unit (OU)
Organization root
Policy
Key (string) -- [REQUIRED]
The key identifier, or name, of the tag.
Value (string) -- [REQUIRED]
The string value that's associated with the key of the tag. You can set the value of a tag to an empty string, but you can't set the value of a tag to null.
dict
Response Syntax
{
'OrganizationalUnit': {
'Id': 'string',
'Arn': 'string',
'Name': 'string',
'Path': 'string'
}
}
Response Structure
(dict) --
OrganizationalUnit (dict) --
A structure that contains details about the newly created OU.
Id (string) --
The unique identifier (ID) associated with this OU. The ID is unique to the organization only.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
Arn (string) --
The Amazon Resource Name (ARN) of this OU.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Name (string) --
The friendly name of this OU.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Path (string) --
The path in the organization where this OU exists.
{'Account': {'Paths': ['string']}}
Retrieves Organizations-related information about the specified account.
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.describe_account(
AccountId='string'
)
string
[REQUIRED]
The unique identifier (ID) of the Amazon Web Services account that you want information about. You can get the ID from the ListAccounts or ListAccountsForParent operations.
The regex pattern for an account ID string requires exactly 12 digits.
dict
Response Syntax
{
'Account': {
'Id': 'string',
'Arn': 'string',
'Email': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE',
'State': 'PENDING_ACTIVATION'|'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE'|'CLOSED',
'Paths': [
'string',
],
'JoinedMethod': 'INVITED'|'CREATED',
'JoinedTimestamp': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Account (dict) --
A structure that contains information about the requested account.
Id (string) --
The unique identifier (ID) of the account.
The regex pattern for an account ID string requires exactly 12 digits.
Arn (string) --
The Amazon Resource Name (ARN) of the account.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Email (string) --
The email address associated with the Amazon Web Services account.
The regex pattern for this parameter is a string of characters that represents a standard internet email address.
Name (string) --
The friendly name of the account.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Status (string) --
The status of the account in the organization.
State (string) --
Each state represents a specific phase in the account lifecycle. Use this information to manage account access, automate workflows, or trigger actions based on account state changes.
For more information about account states and their implications, see Monitor the state of your Amazon Web Services accounts in the Organizations User Guide.
Paths (list) --
The paths in the organization where the account exists.
(string) --
JoinedMethod (string) --
The method by which the account joined the organization.
JoinedTimestamp (datetime) --
The date the account became a part of the organization.
{'OrganizationalUnit': {'Path': 'string'}}
Retrieves information about an organizational unit (OU).
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.describe_organizational_unit(
OrganizationalUnitId='string'
)
string
[REQUIRED]
ID for the organizational unit that you want details about. You can get the ID from the ListOrganizationalUnitsForParent operation.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
dict
Response Syntax
{
'OrganizationalUnit': {
'Id': 'string',
'Arn': 'string',
'Name': 'string',
'Path': 'string'
}
}
Response Structure
(dict) --
OrganizationalUnit (dict) --
A structure that contains details about the specified OU.
Id (string) --
The unique identifier (ID) associated with this OU. The ID is unique to the organization only.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
Arn (string) --
The Amazon Resource Name (ARN) of this OU.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Name (string) --
The friendly name of this OU.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Path (string) --
The path in the organization where this OU exists.
{'Accounts': {'Paths': ['string']}}
Lists all the accounts in the organization. To request only the accounts in a specified root or organizational unit (OU), use the ListAccountsForParent operation instead.
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.list_accounts(
NextToken='string',
MaxResults=123
)
string
The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value of the previous call's NextToken response to indicate where the output should continue from.
integer
The maximum number of items to return in the response. If more results exist than the specified MaxResults value, a token is included in the response so that you can retrieve the remaining results.
dict
Response Syntax
{
'Accounts': [
{
'Id': 'string',
'Arn': 'string',
'Email': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE',
'State': 'PENDING_ACTIVATION'|'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE'|'CLOSED',
'Paths': [
'string',
],
'JoinedMethod': 'INVITED'|'CREATED',
'JoinedTimestamp': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Accounts (list) --
A list of objects in the organization.
(dict) --
Contains information about an Amazon Web Services account that is a member of an organization.
Id (string) --
The unique identifier (ID) of the account.
The regex pattern for an account ID string requires exactly 12 digits.
Arn (string) --
The Amazon Resource Name (ARN) of the account.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Email (string) --
The email address associated with the Amazon Web Services account.
The regex pattern for this parameter is a string of characters that represents a standard internet email address.
Name (string) --
The friendly name of the account.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Status (string) --
The status of the account in the organization.
State (string) --
Each state represents a specific phase in the account lifecycle. Use this information to manage account access, automate workflows, or trigger actions based on account state changes.
For more information about account states and their implications, see Monitor the state of your Amazon Web Services accounts in the Organizations User Guide.
Paths (list) --
The paths in the organization where the account exists.
(string) --
JoinedMethod (string) --
The method by which the account joined the organization.
JoinedTimestamp (datetime) --
The date the account became a part of the organization.
NextToken (string) --
If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.
{'Accounts': {'Paths': ['string']}}
Lists the accounts in an organization that are contained by the specified target root or organizational unit (OU). If you specify the root, you get a list of all the accounts that aren't in any OU. If you specify an OU, you get a list of all the accounts in only that OU and not in any child OUs. To get a list of all accounts in the organization, use the ListAccounts operation.
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.list_accounts_for_parent(
ParentId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The unique identifier (ID) for the parent root or organization unit (OU) whose accounts you want to list.
string
The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value of the previous call's NextToken response to indicate where the output should continue from.
integer
The maximum number of items to return in the response. If more results exist than the specified MaxResults value, a token is included in the response so that you can retrieve the remaining results.
dict
Response Syntax
{
'Accounts': [
{
'Id': 'string',
'Arn': 'string',
'Email': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE',
'State': 'PENDING_ACTIVATION'|'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE'|'CLOSED',
'Paths': [
'string',
],
'JoinedMethod': 'INVITED'|'CREATED',
'JoinedTimestamp': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Accounts (list) --
A list of the accounts in the specified root or OU.
(dict) --
Contains information about an Amazon Web Services account that is a member of an organization.
Id (string) --
The unique identifier (ID) of the account.
The regex pattern for an account ID string requires exactly 12 digits.
Arn (string) --
The Amazon Resource Name (ARN) of the account.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Email (string) --
The email address associated with the Amazon Web Services account.
The regex pattern for this parameter is a string of characters that represents a standard internet email address.
Name (string) --
The friendly name of the account.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Status (string) --
The status of the account in the organization.
State (string) --
Each state represents a specific phase in the account lifecycle. Use this information to manage account access, automate workflows, or trigger actions based on account state changes.
For more information about account states and their implications, see Monitor the state of your Amazon Web Services accounts in the Organizations User Guide.
Paths (list) --
The paths in the organization where the account exists.
(string) --
JoinedMethod (string) --
The method by which the account joined the organization.
JoinedTimestamp (datetime) --
The date the account became a part of the organization.
NextToken (string) --
If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.
{'Accounts': {'Paths': ['string']}}
Lists all the accounts in an organization that have invalid effective policies. An invalid effective policy is an effective policy that fails validation checks, resulting in the effective policy not being fully enforced on all the intended accounts within an organization.
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.list_accounts_with_invalid_effective_policy(
PolicyType='TAG_POLICY'|'BACKUP_POLICY'|'AISERVICES_OPT_OUT_POLICY'|'CHATBOT_POLICY'|'DECLARATIVE_POLICY_EC2'|'SECURITYHUB_POLICY'|'INSPECTOR_POLICY'|'UPGRADE_ROLLOUT_POLICY'|'BEDROCK_POLICY'|'S3_POLICY'|'NETWORK_SECURITY_DIRECTOR_POLICY',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The type of policy that you want information about. You can specify one of the following values:
string
The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value of the previous call's NextToken response to indicate where the output should continue from.
integer
The maximum number of items to return in the response. If more results exist than the specified MaxResults value, a token is included in the response so that you can retrieve the remaining results.
dict
Response Syntax
{
'Accounts': [
{
'Id': 'string',
'Arn': 'string',
'Email': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE',
'State': 'PENDING_ACTIVATION'|'ACTIVE'|'SUSPENDED'|'PENDING_CLOSURE'|'CLOSED',
'Paths': [
'string',
],
'JoinedMethod': 'INVITED'|'CREATED',
'JoinedTimestamp': datetime(2015, 1, 1)
},
],
'PolicyType': 'TAG_POLICY'|'BACKUP_POLICY'|'AISERVICES_OPT_OUT_POLICY'|'CHATBOT_POLICY'|'DECLARATIVE_POLICY_EC2'|'SECURITYHUB_POLICY'|'INSPECTOR_POLICY'|'UPGRADE_ROLLOUT_POLICY'|'BEDROCK_POLICY'|'S3_POLICY'|'NETWORK_SECURITY_DIRECTOR_POLICY',
'NextToken': 'string'
}
Response Structure
(dict) --
Accounts (list) --
The accounts in the organization which have an invalid effective policy for the specified policy type.
(dict) --
Contains information about an Amazon Web Services account that is a member of an organization.
Id (string) --
The unique identifier (ID) of the account.
The regex pattern for an account ID string requires exactly 12 digits.
Arn (string) --
The Amazon Resource Name (ARN) of the account.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Email (string) --
The email address associated with the Amazon Web Services account.
The regex pattern for this parameter is a string of characters that represents a standard internet email address.
Name (string) --
The friendly name of the account.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Status (string) --
The status of the account in the organization.
State (string) --
Each state represents a specific phase in the account lifecycle. Use this information to manage account access, automate workflows, or trigger actions based on account state changes.
For more information about account states and their implications, see Monitor the state of your Amazon Web Services accounts in the Organizations User Guide.
Paths (list) --
The paths in the organization where the account exists.
(string) --
JoinedMethod (string) --
The method by which the account joined the organization.
JoinedTimestamp (datetime) --
The date the account became a part of the organization.
PolicyType (string) --
The specified policy type. One of the following values:
NextToken (string) --
If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.
{'OrganizationalUnits': {'Path': 'string'}}
Lists the organizational units (OUs) in a parent organizational unit or root.
You can only call this operation from the management account or a member account that is a delegated administrator.
See also: AWS API Documentation
Request Syntax
client.list_organizational_units_for_parent(
ParentId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
ID for the root or OU whose child OUs you want to list.
The regex pattern for a parent ID string requires one of the following:
Root - A string that begins with "r-" followed by from 4 to 32 lowercase letters or digits.
Organizational unit (OU) - A string that begins with "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that the OU is in). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
string
The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value of the previous call's NextToken response to indicate where the output should continue from.
integer
The maximum number of items to return in the response. If more results exist than the specified MaxResults value, a token is included in the response so that you can retrieve the remaining results.
dict
Response Syntax
{
'OrganizationalUnits': [
{
'Id': 'string',
'Arn': 'string',
'Name': 'string',
'Path': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
OrganizationalUnits (list) --
A list of the OUs in the specified root or parent OU.
(dict) --
Contains details about an organizational unit (OU). An OU is a container of Amazon Web Services accounts within a root of an organization. Policies that are attached to an OU apply to all accounts contained in that OU and in any child OUs.
Id (string) --
The unique identifier (ID) associated with this OU. The ID is unique to the organization only.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
Arn (string) --
The Amazon Resource Name (ARN) of this OU.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Name (string) --
The friendly name of this OU.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Path (string) --
The path in the organization where this OU exists.
NextToken (string) --
If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.
{'OrganizationalUnit': {'Path': 'string'}}
Renames the specified organizational unit (OU). The ID and ARN don't change. The child OUs and accounts remain in place, and any attached policies of the OU remain attached.
You can only call this operation from the management account.
See also: AWS API Documentation
Request Syntax
client.update_organizational_unit(
OrganizationalUnitId='string',
Name='string'
)
string
[REQUIRED]
ID for the OU that you want to rename. You can get the ID from the ListOrganizationalUnitsForParent operation.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
string
The new name that you want to assign to the OU.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
dict
Response Syntax
{
'OrganizationalUnit': {
'Id': 'string',
'Arn': 'string',
'Name': 'string',
'Path': 'string'
}
}
Response Structure
(dict) --
OrganizationalUnit (dict) --
A structure that contains the details about the specified OU, including its new name.
Id (string) --
The unique identifier (ID) associated with this OU. The ID is unique to the organization only.
The regex pattern for an organizational unit ID string requires "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that contains the OU). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.
Arn (string) --
The Amazon Resource Name (ARN) of this OU.
For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference.
Name (string) --
The friendly name of this OU.
The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
Path (string) --
The path in the organization where this OU exists.