- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
CreateOrganizationalUnitCommand
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.
This operation can be called only from the organization's management account.
Example Syntax
Use a bare-bones client and the command you need to make an API call.
import { OrganizationsClient, CreateOrganizationalUnitCommand } from "@aws-sdk/client-organizations"; // ES Modules import
// const { OrganizationsClient, CreateOrganizationalUnitCommand } = require("@aws-sdk/client-organizations"); // CommonJS import
const client = new OrganizationsClient(config);
const input = { // CreateOrganizationalUnitRequest
ParentId: "STRING_VALUE", // required
Name: "STRING_VALUE", // required
Tags: [ // Tags
{ // Tag
Key: "STRING_VALUE", // required
Value: "STRING_VALUE", // required
},
],
};
const command = new CreateOrganizationalUnitCommand(input);
const response = await client.send(command);
// { // CreateOrganizationalUnitResponse
// OrganizationalUnit: { // OrganizationalUnit
// Id: "STRING_VALUE",
// Arn: "STRING_VALUE",
// Name: "STRING_VALUE",
// },
// };
Example Usage
CreateOrganizationalUnitCommand Input
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
Name Required | string | undefined | The friendly name to assign to the new OU. |
ParentId Required | string | undefined | The unique identifier (ID) of 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:
|
Tags | Tag[] | undefined | 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 If any one of the tags is not valid or if you exceed the allowed number of tags for an OU, then the entire request fails and the OU is not created. |
CreateOrganizationalUnitCommand Output
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
$metadata Required | ResponseMetadata | Metadata pertaining to this request. |
OrganizationalUnit | OrganizationalUnit | undefined | A structure that contains details about the newly created OU. |
Throws
Name | Fault | Details |
---|
Name | Fault | Details |
---|---|---|
AccessDeniedException | client | You don't have permissions to perform the requested operation. The user or role that is making the request must have at least one IAM permissions policy attached that grants the required permissions. For more information, see Access Management in the IAM User Guide. |
AWSOrganizationsNotInUseException | client | Your account isn't a member of an organization. To make this request, you must use the credentials of an account that belongs to an organization. |
ConcurrentModificationException | client | The target of the operation is currently being modified by a different request. Try again later. |
ConstraintViolationException | client | Performing this operation violates a minimum or maximum value limit. For example, attempting to remove the last service control policy (SCP) from an OU or root, inviting or creating too many accounts to the organization, or attaching too many policies to an account, OU, or root. This exception includes a reason that contains additional information about the violated limit: Some of the reasons in the following list might not be applicable to this specific API or operation.
|
DuplicateOrganizationalUnitException | client | An OU with the same name already exists. |
InvalidInputException | client | The requested operation failed because you provided invalid values for one or more of the request parameters. This exception includes a reason that contains additional information about the violated limit: Some of the reasons in the following list might not be applicable to this specific API or operation.
|
ParentNotFoundException | client | We can't find a root or OU with the |
ServiceException | server | Organizations can't complete your request because of an internal service error. Try again later. |
TooManyRequestsException | client | You have sent too many requests in too short a period of time. The quota helps protect against denial-of-service attacks. Try again later. For information about quotas that affect Organizations, see Quotas for Organizations in the Organizations User Guide. |
OrganizationsServiceException | Base exception class for all service exceptions from Organizations service. |