AWS Security Hub Security Hub Configurationpolicyassociation API

openapi: 3.2.0
info:
  title: AWS SecurityHub Configurationpolicyassociation API
  version: '2018-10-26'
  description: Generated from AWS's published Smithy model for AWS SecurityHub. 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://securityhub.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Configurationpolicyassociation
paths:
  /configurationPolicyAssociation/batchget:
    post:
      operationId: BatchGetConfigurationPolicyAssociations
      summary: Batch Get Configuration Policy Associations
      description: Returns associations between an Security Hub CSPM configuration and a batch of target accounts, organizational units, or the root. Only the Security Hub CSPM delegated administrator can invoke this operation from the home Region. A configuration can refer to a configuration policy or to a self-managed configuration.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGetConfigurationPolicyAssociationsResponse'
              example:
                ConfigurationPolicyAssociations:
                - ConfigurationPolicyId: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
                  TargetId: '111122223333'
                  TargetType: ACCOUNT
                  AssociationType: INHERITED
                  UpdatedAt: '2023-01-11T06:17:17.154Z'
                  AssociationStatus: SUCCESS
                  AssociationStatusMessage: This field is only populated for a failed association
                UnprocessedConfigurationPolicyAssociations:
                - ErrorCode: '400'
                  ErrorReason: You do not have sufficient access to perform this action.
                  ConfigurationPolicyAssociationIdentifiers:
                    Target:
                      RootId: r-f6g7h8i9j0example
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalException'
        '401':
          description: InvalidAccessException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAccessException'
        '400':
          description: InvalidInputException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '429':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGetConfigurationPolicyAssociationsRequest'
            example:
              ConfigurationPolicyAssociationIdentifiers:
              - Target:
                  AccountId: '111122223333'
              - Target:
                  RootId: r-f6g7h8i9j0example
      tags:
      - Configurationpolicyassociation
  /configurationPolicyAssociation/get:
    post:
      operationId: GetConfigurationPolicyAssociation
      summary: Get Configuration Policy Association
      description: Returns the association between a configuration and a target account, organizational unit, or the root. The configuration can be a configuration policy or self-managed behavior. Only the Security Hub CSPM delegated administrator can invoke this operation from the home Region.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConfigurationPolicyAssociationResponse'
              example:
                ConfigurationPolicyId: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
                TargetId: '111122223333'
                TargetType: ACCOUNT
                AssociationType: INHERITED
                UpdatedAt: '2023-01-11T06:17:17.154Z'
                AssociationStatus: FAILED
                AssociationStatusMessage: Configuration Policy a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 couldn't be applied to account 111122223333 in us-east-1 Region. Retry your request.
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalException'
        '401':
          description: InvalidAccessException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAccessException'
        '400':
          description: InvalidInputException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '429':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetConfigurationPolicyAssociationRequest'
            example:
              Target:
                AccountId: '111122223333'
      tags:
      - Configurationpolicyassociation
  /configurationPolicyAssociation/list:
    post:
      operationId: ListConfigurationPolicyAssociations
      summary: List Configuration Policy Associations
      description: Provides information about the associations for your configuration policies and self-managed behavior. Only the Security Hub CSPM delegated administrator can invoke this operation from the home Region.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConfigurationPolicyAssociationsResponse'
              example:
                ConfigurationPolicyAssociationSummaries:
                - ConfigurationPolicyId: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
                  TargetId: '123456789012'
                  TargetType: ACCOUNT
                  AssociationType: APPLIED
                  UpdatedAt: '2023-01-11T06:17:17.154Z'
                  AssociationStatus: PENDING
                NextToken: U1FsdGVkX19nBV2zoh+Gou9NgnulLJHWpn9xnG4hqSOfvw3o2JqjI86QDxef
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalException'
        '401':
          description: InvalidAccessException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAccessException'
        '400':
          description: InvalidInputException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '429':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListConfigurationPolicyAssociationsRequest'
            example:
              NextToken: U1FsdGVkX19nBV2zoh+Gou9NgnulLJHWpn9xnG4hqSOhvw3o2JqjI86QDxdf
              MaxResults: 1
              Filters:
                AssociationType: APPLIED
      tags:
      - Configurationpolicyassociation
  /configurationPolicyAssociation/associate:
    post:
      operationId: StartConfigurationPolicyAssociation
      summary: Start Configuration Policy Association
      description: Associates a target account, organizational unit, or the root with a specified configuration. The target can be associated with a configuration policy or self-managed behavior. Only the Security Hub CSPM delegated administrator can invoke this operation from the home Region.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartConfigurationPolicyAssociationResponse'
              example:
                ConfigurationPolicyId: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
                TargetId: '111122223333'
                TargetType: ACCOUNT
                AssociationType: APPLIED
                UpdatedAt: '2023-01-11T06:17:17.154Z'
                AssociationStatus: SUCCESS
                AssociationStatusMessage: This field is populated only if the association fails
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalException'
        '401':
          description: InvalidAccessException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAccessException'
        '400':
          description: InvalidInputException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '429':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConfigurationPolicyAssociationRequest'
            example:
              ConfigurationPolicyIdentifier: arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
              Target:
                AccountId: '111122223333'
      tags:
      - Configurationpolicyassociation
  /configurationPolicyAssociation/disassociate:
    post:
      operationId: StartConfigurationPolicyDisassociation
      summary: Start Configuration Policy Disassociation
      description: Disassociates a target account, organizational unit, or the root from a specified configuration. When you disassociate a configuration from its target, the target inherits the configuration of the closest parent. If there’s no configuration to inherit, the target retains its settings but becomes a self-managed account. A target can be disassociated from a configuration policy or self-managed behavior. Only the Security Hub CSPM delegated administrator can invoke this operation from the home Region.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartConfigurationPolicyDisassociationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalException'
        '401':
          description: InvalidAccessException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAccessException'
        '400':
          description: InvalidInputException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '429':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConfigurationPolicyDisassociationRequest'
            example:
              Target:
                RootId: r-f6g7h8i9j0example
              ConfigurationPolicyIdentifier: SELF_MANAGED_SECURITY_HUB
      tags:
      - Configurationpolicyassociation
components:
  schemas:
    InvalidInputException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    StartConfigurationPolicyDisassociationRequest:
      type: object
      properties:
        Target:
          $ref: '#/components/schemas/Target'
        ConfigurationPolicyIdentifier:
          type: string
          description: The Amazon Resource Name (ARN) of a configuration policy, the universally unique identifier (UUID) of a configuration policy, or a value of SELF_MANAGED_SECURITY_HUB for a self-managed configuration.
      required:
      - ConfigurationPolicyIdentifier
    StartConfigurationPolicyDisassociationResponse:
      type: object
      properties: {}
    Target:
      type: object
      properties:
        AccountId:
          type: string
          description: The Amazon Web Services account ID of the target account.
        OrganizationalUnitId:
          type: string
          description: The organizational unit ID of the target organizational unit.
        RootId:
          type: string
          description: The ID of the organization root.
      description: Exactly one member is set.
    InvalidAccessException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    BatchGetConfigurationPolicyAssociationsRequest:
      type: object
      properties:
        ConfigurationPolicyAssociationIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationPolicyAssociation'
          description: Specifies one or more target account IDs, organizational unit (OU) IDs, or the root ID to retrieve associations for.
      required:
      - ConfigurationPolicyAssociationIdentifiers
    GetConfigurationPolicyAssociationRequest:
      type: object
      properties:
        Target:
          $ref: '#/components/schemas/Target'
      required:
      - Target
    LimitExceededException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    BatchGetConfigurationPolicyAssociationsResponse:
      type: object
      properties:
        ConfigurationPolicyAssociations:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationPolicyAssociationSummary'
          description: Describes associations for the target accounts, OUs, or the root.
        UnprocessedConfigurationPolicyAssociations:
          type: array
          items:
            $ref: '#/components/schemas/UnprocessedConfigurationPolicyAssociation'
          description: An array of configuration policy associations, one for each configuration policy association identifier, that was specified in the request but couldn’t be processed due to an error.
    ConfigurationPolicyAssociation:
      type: object
      properties:
        Target:
          $ref: '#/components/schemas/Target'
    UnprocessedConfigurationPolicyAssociation:
      type: object
      properties:
        ConfigurationPolicyAssociationIdentifiers:
          $ref: '#/components/schemas/ConfigurationPolicyAssociation'
        ErrorCode:
          type: string
          description: An HTTP status code that identifies why the configuration policy association failed.
        ErrorReason:
          type: string
          description: A string that identifies why the configuration policy association failed.
    StartConfigurationPolicyAssociationRequest:
      type: object
      properties:
        ConfigurationPolicyIdentifier:
          type: string
          description: The Amazon Resource Name (ARN) of a configuration policy, the universally unique identifier (UUID) of a configuration policy, or a value of SELF_MANAGED_SECURITY_HUB for a self-managed configuration.
        Target:
          $ref: '#/components/schemas/Target'
      required:
      - ConfigurationPolicyIdentifier
      - Target
    GetConfigurationPolicyAssociationResponse:
      type: object
      properties:
        ConfigurationPolicyId:
          type: string
          description: The universally unique identifier (UUID) of a configuration policy. For self-managed behavior, the value is SELF_MANAGED_SECURITY_HUB.
        TargetId:
          type: string
          description: The target account ID, organizational unit ID, or the root ID for which the association is retrieved.
        TargetType:
          type: string
          enum:
          - ACCOUNT
          - ORGANIZATIONAL_UNIT
          - ROOT
          description: Specifies whether the target is an Amazon Web Services account, organizational unit, or the organization root.
        AssociationType:
          type: string
          enum:
          - INHERITED
          - APPLIED
          description: Indicates whether the association between the specified target and the configuration was directly applied by the Security Hub CSPM delegated administrator or inherited from a parent.
        UpdatedAt:
          type: string
          format: date-time
          description: The date and time, in UTC and ISO 8601 format, that the configuration policy association was last updated.
        AssociationStatus:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILED
          description: The current status of the association between the specified target and the configuration.
        AssociationStatusMessage:
          type: string
          description: The explanation for a FAILED value for AssociationStatus.
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    AssociationFilters:
      type: object
      properties:
        ConfigurationPolicyId:
          type: string
          description: The ARN or UUID of the configuration policy.
        AssociationType:
          type: string
          enum:
          - INHERITED
          - APPLIED
          description: Indicates whether the association between a target and a configuration was directly applied by the Security Hub CSPM delegated administrator or inherited from a parent.
        AssociationStatus:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILED
          description: The current status of the association between a target and a configuration policy.
    StartConfigurationPolicyAssociationResponse:
      type: object
      properties:
        ConfigurationPolicyId:
          type: string
          description: The UUID of the configuration policy.
        TargetId:
          type: string
          description: The identifier of the target account, organizational unit, or the organization root with which the configuration is associated.
        TargetType:
          type: string
          enum:
          - ACCOUNT
          - ORGANIZATIONAL_UNIT
          - ROOT
          description: Indicates whether the target is an Amazon Web Services account, organizational unit, or the organization root.
        AssociationType:
          type: string
          enum:
          - INHERITED
          - APPLIED
          description: Indicates whether the association between the specified target and the configuration was directly applied by the Security Hub CSPM delegated administrator or inherited from a parent.
        UpdatedAt:
          type: string
          format: date-time
          description: The date and time, in UTC and ISO 8601 format, that the configuration policy association was last updated.
        AssociationStatus:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILED
          description: The current status of the association between the specified target and the configuration.
        AssociationStatusMessage:
          type: string
          description: An explanation for a FAILED value for AssociationStatus.
    ConfigurationPolicyAssociationSummary:
      type: object
      properties:
        ConfigurationPolicyId:
          type: string
          description: The universally unique identifier (UUID) of the configuration policy.
        TargetId:
          type: string
          description: The identifier of the target account, organizational unit, or the root.
        TargetType:
          type: string
          enum:
          - ACCOUNT
          - ORGANIZATIONAL_UNIT
          - ROOT
          description: Specifies whether the target is an Amazon Web Services account, organizational unit, or the root.
        AssociationType:
          type: string
          enum:
          - INHERITED
          - APPLIED
          description: Indicates whether the association between the specified target and the configuration was directly applied by the Security Hub CSPM delegated administrator or inherited from a parent.
        UpdatedAt:
          type: string
          format: date-time
          description: The date and time, in UTC and ISO 8601 format, that the configuration policy association was last updated.
        AssociationStatus:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILED
          description: The current status of the association between the specified target and the configuration.
        AssociationStatusMessage:
          type: string
          description: The explanation for a FAILED value for AssociationStatus.
    ListConfigurationPolicyAssociationsRequest:
      type: object
      properties:
        NextToken:
          type: string
          description: The NextToken value that's returned from a previous paginated ListConfigurationPolicyAssociations request where MaxResults was used but the results exceeded the value of that parameter. Pagination continues from the end of the previous response that returned the NextToken value. This value is null when there are no more results to return.
        MaxResults:
          type: integer
          description: The maximum number of results that's returned by ListConfigurationPolicies in each page of the response. When this parameter is used, ListConfigurationPolicyAssociations returns the specified number of results in a single page and a NextToken response element. You can see the remaining results of the initial request by sending another ListConfigurationPolicyAssociations request with the returned NextToken value. A valid range for MaxResults is between 1 and 100.
        Filters:
          $ref: '#/components/schemas/AssociationFilters'
    ListConfigurationPolicyAssociationsResponse:
      type: object
      properties:
        ConfigurationPolicyAssociationSummaries:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationPolicyAssociationSummary'
          description: An object that contains the details of each configuration policy association that’s returned in a ListConfigurationPolicyAssociations request.
        NextToken:
          type: string
          description: The NextToken value to include in the next ListConfigurationPolicyAssociations request. When the results of a ListConfigurationPolicyAssociations request exceed MaxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
    InternalException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
  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: securityhub
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/securityhub/service/2018-10-26/securityhub-2018-10-26.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)