Amazon Kendra Kendra Principal Mapping API

openapi: 3.2.0
info:
  title: AWSKendraFrontendService Principal Mapping API
  version: '2019-02-03'
  description: Generated from AWS's published Smithy model for AWSKendraFrontendService. 3 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://kendra.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Principal Mapping
paths:
  /#DeletePrincipalMapping:
    post:
      operationId: DeletePrincipalMapping
      summary: Delete Principal Mapping
      description: Deletes a group so that all users that belong to the group can no longer access documents only available to that group. For example, after deleting the group "Summer Interns", all interns who belonged to that group no longer see intern-only documents in their search results. If you want to delete or replace users or sub groups of a group, you need to use the PutPrincipalMapping operation. For example, if a user in the group "Engineering" leaves the engineering team and another user takes their place, you provide an updated list of users or sub groups that belong to the "Engineering" group when calling PutPrincipalMapping. You can update your internal list of users or sub groups and input this list when calling PutPrincipalMapping. DeletePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region.
      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'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ValidationException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSKendraFrontendService.DeletePrincipalMapping
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeletePrincipalMappingRequest'
      tags:
      - Principal Mapping
  /#DescribePrincipalMapping:
    post:
      operationId: DescribePrincipalMapping
      summary: Describe Principal Mapping
      description: Describes the processing of PUT and DELETE actions for mapping users to their groups. This includes information on the status of actions currently processing or yet to be processed, when actions were last updated, when actions were received by Amazon Kendra, the latest action that should process and apply after other actions, and useful error messages if an action could not be processed. DescribePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribePrincipalMappingResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ValidationException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSKendraFrontendService.DescribePrincipalMapping
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribePrincipalMappingRequest'
      tags:
      - Principal Mapping
  /#PutPrincipalMapping:
    post:
      operationId: PutPrincipalMapping
      summary: Put Principal Mapping
      description: Maps users to their groups so that you only need to provide the user ID when you issue the query. You can also map sub groups to groups. For example, the group "Company Intellectual Property Teams" includes sub groups "Research" and "Engineering". These sub groups include their own list of users or people who work in these teams. Only users who work in research and engineering, and therefore belong in the intellectual property group, can see top-secret company documents in their search results. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. For more information, see Filtering on user context. If more than five PUT actions for a group are currently processing, a validation exception is thrown.
      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'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ValidationException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSKendraFrontendService.PutPrincipalMapping
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/PutPrincipalMappingRequest'
      tags:
      - Principal Mapping
components:
  schemas:
    PutPrincipalMappingRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index you want to map users to their groups.
        DataSourceId:
          type: string
          description: The identifier of the data source you want to map users to their groups. This is useful if a group is tied to multiple data sources, but you only want the group to access documents of a certain data source. For example, the groups "Research", "Engineering", and "Sales and Marketing" are all tied to the company's documents stored in the data sources Confluence and Salesforce. However, "Sales and Marketing" team only needs access to customer-related documents stored in Salesforce.
        GroupId:
          type: string
          description: The identifier of the group you want to map its users to.
        GroupMembers:
          $ref: '#/components/schemas/GroupMembers'
        OrderingId:
          type: integer
          description: 'The timestamp identifier you specify to ensure Amazon Kendra doesn''t override the latest PUT action with previous actions. The highest number ID, which is the ordering ID, is the latest action you want to process and apply on top of other actions with lower number IDs. This prevents previous actions with lower number IDs from possibly overriding the latest action. The ordering ID can be the Unix time of the last update you made to a group members list. You would then provide this list when calling PutPrincipalMapping. This ensures your PUT action for that updated group with the latest members '
        RoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role that has access to the S3 file that contains your list of users that belong to a group. For more information, see IAM roles for Amazon Kendra.
      required:
      - IndexId
      - GroupId
      - GroupMembers
    DeletePrincipalMappingRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index you want to delete a group from.
        DataSourceId:
          type: string
          description: The identifier of the data source you want to delete a group from. A group can be tied to multiple data sources. You can delete a group from accessing documents in a certain data source. For example, the groups "Research", "Engineering", and "Sales and Marketing" are all tied to the company's documents stored in the data sources Confluence and Salesforce. You want to delete "Research" and "Engineering" groups from Salesforce, so that these groups cannot access customer-related documents stored in Salesforce. Only "Sales and Marketing" should access documents in the Salesforce data source.
        GroupId:
          type: string
          description: The identifier of the group you want to delete.
        OrderingId:
          type: integer
          description: The timestamp identifier you specify to ensure Amazon Kendra does not override the latest DELETE action with previous actions. The highest number ID, which is the ordering ID, is the latest action you want to process and apply on top of other actions with lower number IDs. This prevents previous actions with lower number IDs from possibly overriding the latest action. The ordering ID can be the Unix time of the last update you made to a group members list. You would then provide this list when calling PutPrincipalMapping. This ensures your DELETE action for that updated group with the latest m
      required:
      - IndexId
      - GroupId
    MemberGroup:
      type: object
      properties:
        GroupId:
          type: string
          description: The identifier of the sub group you want to map to a group.
        DataSourceId:
          type: string
          description: The identifier of the data source for the sub group you want to map to a group.
      required:
      - GroupId
    ConflictException:
      type: object
      properties:
        Message:
          type: string
    DescribePrincipalMappingRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index required to check the processing of PUT and DELETE actions for mapping users to their groups.
        DataSourceId:
          type: string
          description: The identifier of the data source to check the processing of PUT and DELETE actions for mapping users to their groups.
        GroupId:
          type: string
          description: The identifier of the group required to check the processing of PUT and DELETE actions for mapping users to their groups.
      required:
      - IndexId
      - GroupId
    GroupMembers:
      type: object
      properties:
        MemberGroups:
          type: array
          items:
            $ref: '#/components/schemas/MemberGroup'
          description: A list of users that belong to a group. This can also include sub groups. For example, the sub groups "Research", "Engineering", and "Sales and Marketing" all belong to the group "Company A".
        MemberUsers:
          type: array
          items:
            $ref: '#/components/schemas/MemberUser'
          description: A list of users that belong to a group. For example, a list of interns all belong to the "Interns" group.
        S3PathforGroupMembers:
          $ref: '#/components/schemas/S3Path'
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
    MemberUser:
      type: object
      properties:
        UserId:
          type: string
          description: The identifier of the user you want to map to a group.
      required:
      - UserId
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    DescribePrincipalMappingResponse:
      type: object
      properties:
        IndexId:
          type: string
          description: Shows the identifier of the index to see information on the processing of PUT and DELETE actions for mapping users to their groups.
        DataSourceId:
          type: string
          description: Shows the identifier of the data source to see information on the processing of PUT and DELETE actions for mapping users to their groups.
        GroupId:
          type: string
          description: Shows the identifier of the group to see information on the processing of PUT and DELETE actions for mapping users to their groups.
        GroupOrderingIdSummaries:
          type: array
          items:
            $ref: '#/components/schemas/GroupOrderingIdSummary'
          description: 'Shows the following information on the processing of PUT and DELETE actions for mapping users to their groups: Status—the status can be either PROCESSING, SUCCEEDED, DELETING, DELETED, or FAILED. Last updated—the last date-time an action was updated. Received—the last date-time an action was received or submitted. Ordering ID—the latest action that should process and apply after other actions. Failure reason—the reason an action could not be processed.'
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    S3Path:
      type: object
      properties:
        Bucket:
          type: string
          description: The name of the S3 bucket that contains the file.
        Key:
          type: string
          description: The name of the file.
      required:
      - Bucket
      - Key
    ValidationException:
      type: object
      properties:
        Message:
          type: string
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
    GroupOrderingIdSummary:
      type: object
      properties:
        Status:
          type: string
          enum:
          - FAILED
          - SUCCEEDED
          - PROCESSING
          - DELETING
          - DELETED
          description: The current processing status of actions for mapping users to their groups. The status can be either PROCESSING, SUCCEEDED, DELETING, DELETED, or FAILED.
        LastUpdatedAt:
          type: string
          format: date-time
          description: The Unix timestamp when an action was last updated. An action can be a PUT or DELETE action for mapping users to their groups.
        ReceivedAt:
          type: string
          format: date-time
          description: The Unix timestamp when an action was received by Amazon Kendra. An action can be a PUT or DELETE action for mapping users to their groups.
        OrderingId:
          type: integer
          description: The order in which actions should complete processing. An action can be a PUT or DELETE action for mapping users to their groups.
        FailureReason:
          type: string
          description: The reason an action could not be processed. An action can be a PUT or DELETE action for mapping users to their groups.
  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: kendra
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/kendra/service/2019-02-03/kendra-2019-02-03.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)