Amazon Detective Members API

openapi: 3.1.0
info:
  title: Amazon Detective Members API
  version: '2018-10-26'
  description: Generated from AWS's published Smithy model for Amazon Detective. 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://api.detective.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /graph/members:
    post:
      operationId: CreateMembers
      summary: Create Members
      description: 'CreateMembers is used to send invitations to accounts. For the organization behavior graph, the Detective
        administrator account uses CreateMembers to enable organization accounts as member accounts. For invited accounts,
        CreateMembers sends a request to invite the specified Amazon Web Services accounts to be member accounts in the behavior
        graph. This operation can only be called by the administrator account for a behavior graph. CreateMembers verifies
        the accounts and then invites the verified accounts. The administrator can optionally specify to not send invitation
        emails to the member accounts. This would be used when the administrator manages their member accounts centrally.
        For organization accounts in the organization behavior graph, CreateMembers attempts to enable the accounts. The organization
        accounts do not receive invitations. The request provides the behavior graph ARN and the list of accounts to invite
        or to enable. The response separates the requested accounts into two lists: The accounts that CreateMembers was able
        to process. For invited accounts, includes member accounts that are being verified, that have passed verification
        and are to be invited, and that have fa'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMembersResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMembersRequest'
      tags:
      - Members
  /graph/members/removal:
    post:
      operationId: DeleteMembers
      summary: Delete Members
      description: Removes the specified member accounts from the behavior graph. The removed accounts no longer contribute
        data to the behavior graph. This operation can only be called by the administrator account for the behavior graph.
        For invited accounts, the removed accounts are deleted from the list of accounts in the behavior graph. To restore
        the account, the administrator account must send another invitation. For organization accounts in the organization
        behavior graph, the Detective administrator account can always enable the organization account again. Organization
        accounts that are not enabled as member accounts are not included in the ListMembers results for the organization
        behavior graph. An administrator account cannot use DeleteMembers to remove their own account from the behavior graph.
        To disable a behavior graph, the administrator account uses the DeleteGraph API method.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMembersResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembersRequest'
      tags:
      - Members
  /graph/members/get:
    post:
      operationId: GetMembers
      summary: Get Members
      description: Returns the membership details for specified member accounts for a behavior graph.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMembersResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMembersRequest'
      tags:
      - Members
  /graph/members/list:
    post:
      operationId: ListMembers
      summary: List Members
      description: Retrieves the list of member accounts for a behavior graph. For invited accounts, the results do not include
        member accounts that were removed from the behavior graph. For the organization behavior graph, the results do not
        include organization accounts that the Detective administrator account has not enabled as member accounts.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMembersResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListMembersRequest'
      tags:
      - Members
  /graph/member/monitoringstate:
    post:
      operationId: StartMonitoringMember
      summary: Start Monitoring Member
      description: Sends a request to enable data ingest for a member account that has a status of ACCEPTED_BUT_DISABLED.
        For valid member accounts, the status is updated as follows. If Detective enabled the member account, then the new
        status is ENABLED. If Detective cannot enable the member account, the status remains ACCEPTED_BUT_DISABLED.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMonitoringMemberRequest'
      tags:
      - Members
components:
  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: detective
  schemas:
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        ErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The SDK default error code associated with the access denied exception.
        ErrorCodeReason:
          type: string
          description: The SDK default explanation of why access was denied.
        SubErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The error code associated with the access denied exception.
        SubErrorCodeReason:
          type: string
          description: An explanation of why access was denied.
    Account:
      type: object
      properties:
        AccountId:
          type: string
          description: The account identifier of the Amazon Web Services account.
        EmailAddress:
          type: string
          description: The Amazon Web Services account root user email address for the Amazon Web Services account.
      required:
      - AccountId
      - EmailAddress
    ConflictException:
      type: object
      properties:
        Message:
          type: string
    CreateMembersRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The ARN of the behavior graph.
        Message:
          type: string
          description: Customized message text to include in the invitation email message to the invited member accounts.
        DisableEmailNotification:
          type: boolean
          description: if set to true, then the invited accounts do not receive email notifications. By default, this is set
            to false, and the invited accounts receive email notifications. Organization accounts in the organization behavior
            graph do not receive email notifications.
        Accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
          description: The list of Amazon Web Services accounts to invite or to enable. You can invite or enable up to 50
            accounts at a time. For each invited account, the account list contains the account identifier and the Amazon
            Web Services account root user email address. For organization accounts in the organization behavior graph, the
            email address is not required.
      required:
      - GraphArn
      - Accounts
    CreateMembersResponse:
      type: object
      properties:
        Members:
          type: array
          items:
            $ref: '#/components/schemas/MemberDetail'
          description: The set of member account invitation or enablement requests that Detective was able to process. This
            includes accounts that are being verified, that failed verification, and that passed verification and are being
            sent an invitation or are being enabled.
        UnprocessedAccounts:
          type: array
          items:
            $ref: '#/components/schemas/UnprocessedAccount'
          description: The list of accounts for which Detective was unable to process the invitation or enablement request.
            For each account, the list provides the reason why the request could not be processed. The list includes accounts
            that are already member accounts in the behavior graph.
    DatasourcePackageUsageInfo:
      type: object
      properties:
        VolumeUsageInBytes:
          type: integer
          description: Total volume of data in bytes per day ingested for a given data source package.
        VolumeUsageUpdateTime:
          type: string
          format: date-time
          description: The data and time when the member account data volume was last updated. The value is an ISO8601 formatted
            string. For example, 2021-08-18T16:35:56.284Z.
    DeleteMembersRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The ARN of the behavior graph to remove members from.
        AccountIds:
          type: array
          items:
            type: string
          description: The list of Amazon Web Services account identifiers for the member accounts to remove from the behavior
            graph. You can remove up to 50 member accounts at a time.
      required:
      - GraphArn
      - AccountIds
    DeleteMembersResponse:
      type: object
      properties:
        AccountIds:
          type: array
          items:
            type: string
          description: The list of Amazon Web Services account identifiers for the member accounts that Detective successfully
            removed from the behavior graph.
        UnprocessedAccounts:
          type: array
          items:
            $ref: '#/components/schemas/UnprocessedAccount'
          description: The list of member accounts that Detective was not able to remove from the behavior graph. For each
            member account, provides the reason that the deletion could not be processed.
    GetMembersRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The ARN of the behavior graph for which to request the member details.
        AccountIds:
          type: array
          items:
            type: string
          description: The list of Amazon Web Services account identifiers for the member account for which to return member
            details. You can request details for up to 50 member accounts at a time. You cannot use GetMembers to retrieve
            information about member accounts that were removed from the behavior graph.
      required:
      - GraphArn
      - AccountIds
    GetMembersResponse:
      type: object
      properties:
        MemberDetails:
          type: array
          items:
            $ref: '#/components/schemas/MemberDetail'
          description: The member account details that Detective is returning in response to the request.
        UnprocessedAccounts:
          type: array
          items:
            $ref: '#/components/schemas/UnprocessedAccount'
          description: The requested member accounts for which Detective was unable to return member details. For each account,
            provides the reason why the request could not be processed.
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    ListMembersRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The ARN of the behavior graph for which to retrieve the list of member accounts.
        NextToken:
          type: string
          description: For requests to retrieve the next page of member account results, the pagination token that was returned
            with the previous page of results. The initial request does not include a pagination token.
        MaxResults:
          type: integer
          description: The maximum number of member accounts to include in the response. The total must be less than the overall
            limit on the number of results to return, which is currently 200.
      required:
      - GraphArn
    ListMembersResponse:
      type: object
      properties:
        MemberDetails:
          type: array
          items:
            $ref: '#/components/schemas/MemberDetail'
          description: The list of member accounts in the behavior graph. For invited accounts, the results include member
            accounts that did not pass verification and member accounts that have not yet accepted the invitation to the behavior
            graph. The results do not include member accounts that were removed from the behavior graph. For the organization
            behavior graph, the results do not include organization accounts that the Detective administrator account has
            not enabled as member accounts.
        NextToken:
          type: string
          description: If there are more member accounts remaining in the results, then use this pagination token to request
            the next page of member accounts.
    MemberDetail:
      type: object
      properties:
        AccountId:
          type: string
          description: The Amazon Web Services account identifier for the member account.
        EmailAddress:
          type: string
          description: The Amazon Web Services account root user email address for the member account.
        GraphArn:
          type: string
          description: The ARN of the behavior graph.
        MasterId:
          type: string
          description: The Amazon Web Services account identifier of the administrator account for the behavior graph.
        AdministratorId:
          type: string
          description: The Amazon Web Services account identifier of the administrator account for the behavior graph.
        Status:
          type: string
          enum:
          - INVITED
          - VERIFICATION_IN_PROGRESS
          - VERIFICATION_FAILED
          - ENABLED
          - ACCEPTED_BUT_DISABLED
          description: 'The current membership status of the member account. The status can have one of the following values:
            INVITED - For invited accounts only. Indicates that the member was sent an invitation but has not yet responded.
            VERIFICATION_IN_PROGRESS - For invited accounts only, indicates that Detective is verifying that the account identifier
            and email address provided for the member account match. If they do match, then Detective sends the invitation.
            If the email address and account identifier don''t match, then the member cannot be added to the behavior graph.
            For organization accounts in the organiza'
        DisabledReason:
          type: string
          enum:
          - VOLUME_TOO_HIGH
          - VOLUME_UNKNOWN
          description: 'For member accounts with a status of ACCEPTED_BUT_DISABLED, the reason that the member account is
            not enabled. The reason can have one of the following values: VOLUME_TOO_HIGH - Indicates that adding the member
            account would cause the data volume for the behavior graph to be too high. VOLUME_UNKNOWN - Indicates that Detective
            is unable to verify the data volume for the member account. This is usually because the member account is not
            enrolled in Amazon GuardDuty.'
        InvitedTime:
          type: string
          format: date-time
          description: For invited accounts, the date and time that Detective sent the invitation to the account. The value
            is an ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.
        UpdatedTime:
          type: string
          format: date-time
          description: The date and time that the member account was last updated. The value is an ISO8601 formatted string.
            For example, 2021-08-18T16:35:56.284Z.
        VolumeUsageInBytes:
          type: integer
          description: The data volume in bytes per day for the member account.
        VolumeUsageUpdatedTime:
          type: string
          format: date-time
          description: The data and time when the member account data volume was last updated. The value is an ISO8601 formatted
            string. For example, 2021-08-18T16:35:56.284Z.
        PercentOfGraphUtilization:
          type: number
          description: The member account data volume as a percentage of the maximum allowed data volume. 0 indicates 0 percent,
            and 100 indicates 100 percent. Note that this is not the percentage of the behavior graph data volume. For example,
            the data volume for the behavior graph is 80 GB per day. The maximum data volume is 160 GB per day. If the data
            volume for the member account is 40 GB per day, then PercentOfGraphUtilization is 25. It represents 25% of the
            maximum allowed data volume.
        PercentOfGraphUtilizationUpdatedTime:
          type: string
          format: date-time
          description: The date and time when the graph utilization percentage was last updated. The value is an ISO8601 formatted
            string. For example, 2021-08-18T16:35:56.284Z.
        InvitationType:
          type: string
          enum:
          - INVITATION
          - ORGANIZATION
          description: The type of behavior graph membership. For an organization account in the organization behavior graph,
            the type is ORGANIZATION. For an account that was invited to a behavior graph, the type is INVITATION.
        VolumeUsageByDatasourcePackage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DatasourcePackageUsageInfo'
          description: Details on the volume of usage for each data source package in a behavior graph.
        DatasourcePackageIngestStates:
          type: object
          additionalProperties:
            type: string
            enum:
            - STARTED
            - STOPPED
            - DISABLED
          description: The state of a data source package for the behavior graph.
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
        Resources:
          type: array
          items:
            type: string
          description: The type of resource that has exceeded the service quota.
    StartMonitoringMemberRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The ARN of the behavior graph.
        AccountId:
          type: string
          description: The account ID of the member account to try to enable. The account must be an invited member account
            with a status of ACCEPTED_BUT_DISABLED.
      required:
      - GraphArn
      - AccountId
    UnprocessedAccount:
      type: object
      properties:
        AccountId:
          type: string
          description: The Amazon Web Services account identifier of the member account that was not processed.
        Reason:
          type: string
          description: The reason that the member account request could not be processed.
    ValidationException:
      type: object
      properties:
        Message:
          type: string
        ErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The error code associated with the validation failure.
        ErrorCodeReason:
          type: string
          description: An explanation of why validation failed.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/detective/service/2018-10-26/detective-2018-10-26.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)