Amazon Organizations Organizations Organizational Unit API

openapi: 3.2.0
info:
  title: AWS Organizations Organizational Unit API
  version: '2016-11-28'
  description: Generated from AWS's published Smithy model for AWS Organizations. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://organizations.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Organizational Unit
paths:
  /#CreateOrganizationalUnit:
    post:
      operationId: CreateOrganizationalUnit
      summary: Create Organizational Unit
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateOrganizationalUnitResponse'
              example:
                OrganizationalUnit:
                  Id: ou-examplerootid111-exampleouid111
                  Arn: arn:aws:organizations::111111111111:ou/o-exampleorgid/ou-examplerootid111-exampleouid111
                  Name: AccountingOU
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: AWSOrganizationsNotInUseException; ParentNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AWSOrganizationsNotInUseException'
        '409':
          description: ConcurrentModificationException; ConstraintViolationException; DuplicateOrganizationalUnitException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConcurrentModificationException'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '500':
          description: ServiceException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '429':
          description: TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSOrganizationsV20161128.CreateOrganizationalUnit
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateOrganizationalUnitRequest'
            example:
              ParentId: r-examplerootid111
              Name: AccountingOU
      tags:
      - Organizational Unit
  /#DeleteOrganizationalUnit:
    post:
      operationId: DeleteOrganizationalUnit
      summary: Delete Organizational Unit
      description: Deletes an organizational unit (OU) from a root or another OU. You must first remove all accounts and child OUs from the OU that you want to delete. You can only call this operation from the management account.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                type: string
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: AWSOrganizationsNotInUseException; OrganizationalUnitNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AWSOrganizationsNotInUseException'
        '409':
          description: ConcurrentModificationException; OrganizationalUnitNotEmptyException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConcurrentModificationException'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '500':
          description: ServiceException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '429':
          description: TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSOrganizationsV20161128.DeleteOrganizationalUnit
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteOrganizationalUnitRequest'
            example:
              OrganizationalUnitId: ou-examplerootid111-exampleouid111
      tags:
      - Organizational Unit
  /#DescribeOrganizationalUnit:
    post:
      operationId: DescribeOrganizationalUnit
      summary: Describe Organizational Unit
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeOrganizationalUnitResponse'
              example:
                OrganizationalUnit:
                  Name: Accounting Group
                  Arn: arn:aws:organizations::111111111111:ou/o-exampleorgid/ou-examplerootid111-exampleouid111
                  Id: ou-examplerootid111-exampleouid111
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: AWSOrganizationsNotInUseException; OrganizationalUnitNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AWSOrganizationsNotInUseException'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '500':
          description: ServiceException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '429':
          description: TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSOrganizationsV20161128.DescribeOrganizationalUnit
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeOrganizationalUnitRequest'
            example:
              OrganizationalUnitId: ou-examplerootid111-exampleouid111
      tags:
      - Organizational Unit
  /#ListOrganizationalUnitsForParent:
    post:
      operationId: ListOrganizationalUnitsForParent
      summary: List Organizational Units For Parent
      description: Lists the organizational units (OUs) in a parent organizational unit or root. When calling List* operations, always check the NextToken response parameter value, even if you receive an empty result set. These operations can occasionally return an empty set of results even when more results are available. Continue making requests until NextToken returns null. A null NextToken value indicates that you have retrieved all available results. You can only call this operation from the management account or a member account that is a delegated administrator.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListOrganizationalUnitsForParentResponse'
              example:
                OrganizationalUnits:
                - Id: ou-examplerootid111-exampleouid111
                  Arn: arn:aws:organizations::111111111111:ou/o-exampleorgid/ou-examlerootid111-exampleouid111
                  Name: Development
                - Id: ou-examplerootid111-exampleouid222
                  Arn: arn:aws:organizations::111111111111:ou/o-exampleorgid/ou-examlerootid111-exampleouid222
                  Name: Production
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: AWSOrganizationsNotInUseException; ParentNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AWSOrganizationsNotInUseException'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '500':
          description: ServiceException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '429':
          description: TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSOrganizationsV20161128.ListOrganizationalUnitsForParent
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListOrganizationalUnitsForParentRequest'
            example:
              ParentId: r-examplerootid111
      tags:
      - Organizational Unit
  /#UpdateOrganizationalUnit:
    post:
      operationId: UpdateOrganizationalUnit
      summary: Update Organizational Unit
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateOrganizationalUnitResponse'
              example:
                OrganizationalUnit:
                  Id: ou-examplerootid111-exampleouid111
                  Name: AccountingOU
                  Arn: arn:aws:organizations::111111111111:ou/o-exampleorgid/ou-examplerootid111-exampleouid111
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: AWSOrganizationsNotInUseException; OrganizationalUnitNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AWSOrganizationsNotInUseException'
        '409':
          description: ConcurrentModificationException; DuplicateOrganizationalUnitException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConcurrentModificationException'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '500':
          description: ServiceException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '429':
          description: TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSOrganizationsV20161128.UpdateOrganizationalUnit
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationalUnitRequest'
            example:
              OrganizationalUnitId: ou-examplerootid111-exampleouid111
              Name: AccountingOU
      tags:
      - Organizational Unit
components:
  schemas:
    InvalidInputException:
      type: object
      properties:
        Message:
          type: string
        Reason:
          type: string
          enum:
          - INVALID_PARTY_TYPE_TARGET
          - INVALID_SYNTAX_ORGANIZATION_ARN
          - INVALID_SYNTAX_POLICY_ID
          - INVALID_ENUM
          - INVALID_ENUM_POLICY_TYPE
          - INVALID_LIST_MEMBER
          - MAX_LENGTH_EXCEEDED
          - MAX_VALUE_EXCEEDED
          - MIN_LENGTH_EXCEEDED
          - MIN_VALUE_EXCEEDED
          - IMMUTABLE_POLICY
          - INVALID_PATTERN
          - INVALID_PATTERN_TARGET_ID
          - INPUT_REQUIRED
          - INVALID_NEXT_TOKEN
          - MAX_LIMIT_EXCEEDED_FILTER
          - MOVING_ACCOUNT_BETWEEN_DIFFERENT_ROOTS
          - INVALID_FULL_NAME_TARGET
          - UNRECOGNIZED_SERVICE_PRINCIPAL
          - INVALID_ROLE_NAME
          - INVALID_SYSTEM_TAGS_PARAMETER
          - DUPLICATE_TAG_KEY
          - TARGET_NOT_SUPPORTED
          - INVALID_EMAIL_ADDRESS_TARGET
          - INVALID_RESOURCE_POLICY_JSON
          - INVALID_PRINCIPAL
          - UNSUPPORTED_ACTION_IN_RESOURCE_POLICY
          - UNSUPPORTED_POLICY_TYPE_IN_RESOURCE_POLICY
          - UNSUPPORTED_RESOURCE_IN_RESOURCE_POLICY
          - NON_DETACHABLE_POLICY
          - CALLER_REQUIRED_FIELD_MISSING
          - UNSUPPORTED_ACTION_IN_RESPONSIBILITY_TRANSFER
          - START_DATE_NOT_BEGINNING_OF_MONTH
          - START_DATE_NOT_BEGINNING_OF_DAY
          - START_DATE_TOO_EARLY
          - START_DATE_TOO_LATE
          - INVALID_START_DATE
          - END_DATE_NOT_END_OF_MONTH
          - END_DATE_TOO_EARLY
          - END_DATE_TOO_LATE
          - INVALID_END_DATE
    UpdateOrganizationalUnitRequest:
      type: object
      properties:
        OrganizationalUnitId:
          type: string
          description: 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.
        Name:
          type: string
          description: 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.
      required:
      - OrganizationalUnitId
    Tag:
      type: object
      properties:
        Key:
          type: string
          description: The key identifier, or name, of the tag.
        Value:
          type: string
          description: 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.
      required:
      - Key
      - Value
    ListOrganizationalUnitsForParentResponse:
      type: object
      properties:
        OrganizationalUnits:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationalUnit'
          description: A list of the OUs in the specified root or parent OU.
        NextToken:
          type: string
          description: 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.
    DeleteOrganizationalUnitRequest:
      type: object
      properties:
        OrganizationalUnitId:
          type: string
          description: ID for the organizational unit that you want to delete. 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.
      required:
      - OrganizationalUnitId
    DescribeOrganizationalUnitResponse:
      type: object
      properties:
        OrganizationalUnit:
          $ref: '#/components/schemas/OrganizationalUnit'
    OrganizationalUnit:
      type: object
      properties:
        Id:
          type: string
          description: 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:
          type: string
          description: 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:
          type: string
          description: 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:
          type: string
          description: The path in the organization where this OU exists.
    CreateOrganizationalUnitRequest:
      type: object
      properties:
        ParentId:
          type: string
          description: '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.'
        Name:
          type: string
          description: The friendly name to assign to the new OU.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: 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. 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.
      required:
      - ParentId
      - Name
    DescribeOrganizationalUnitRequest:
      type: object
      properties:
        OrganizationalUnitId:
          type: string
          description: 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.
      required:
      - OrganizationalUnitId
    AWSOrganizationsNotInUseException:
      type: object
      properties:
        Message:
          type: string
    CreateOrganizationalUnitResponse:
      type: object
      properties:
        OrganizationalUnit:
          $ref: '#/components/schemas/OrganizationalUnit'
    TooManyRequestsException:
      type: object
      properties:
        Type:
          type: string
        Message:
          type: string
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
    ConcurrentModificationException:
      type: object
      properties:
        Message:
          type: string
    ListOrganizationalUnitsForParentRequest:
      type: object
      properties:
        ParentId:
          type: string
          description: '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.'
        NextToken:
          type: string
          description: 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.
        MaxResults:
          type: integer
          description: 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.
      required:
      - ParentId
    ServiceException:
      type: object
      properties:
        Message:
          type: string
    UpdateOrganizationalUnitResponse:
      type: object
      properties:
        OrganizationalUnit:
          $ref: '#/components/schemas/OrganizationalUnit'
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: organizations
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/organizations/service/2016-11-28/organizations-2016-11-28.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)