Amazon Kendra Kendra Access Control Configuration API

openapi: 3.2.0
info:
  title: AWSKendraFrontendService Access Control Configuration API
  version: '2019-02-03'
  description: Generated from AWS's published Smithy model for AWSKendraFrontendService. 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://kendra.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Access Control Configuration
paths:
  /#CreateAccessControlConfiguration:
    post:
      operationId: CreateAccessControlConfiguration
      summary: Create Access Control Configuration
      description: Creates an access configuration for your documents. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can use this to re-configure your existing document level access control without indexing all of your documents again. For example, your index contains top-secret company documents that only certain employees or users should access. One of these users leaves the company or switches to a team that should be blocked from accessing top-secret documents. The user still has access to top-secret documents because the user had access when your documents were previously indexed. You can create a specific access control configuration for the user with deny access. You can later update the access control configuration to allow access if the user returns to the company and re-joins the 'top-secret' team. You can re-configure access control for your documents as circumstances change. To apply your access control configuration to certain documents, you call the BatchPutDocument API with the AccessControlConfigurationId included in the Document
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateAccessControlConfigurationResponse'
        '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.CreateAccessControlConfiguration
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateAccessControlConfigurationRequest'
      tags:
      - Access Control Configuration
  /#DeleteAccessControlConfiguration:
    post:
      operationId: DeleteAccessControlConfiguration
      summary: Delete Access Control Configuration
      description: Deletes an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteAccessControlConfigurationResponse'
        '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.DeleteAccessControlConfiguration
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteAccessControlConfigurationRequest'
      tags:
      - Access Control Configuration
  /#DescribeAccessControlConfiguration:
    post:
      operationId: DescribeAccessControlConfiguration
      summary: Describe Access Control Configuration
      description: Gets information about an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeAccessControlConfigurationResponse'
        '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.DescribeAccessControlConfiguration
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeAccessControlConfigurationRequest'
      tags:
      - Access Control Configuration
  /#ListAccessControlConfigurations:
    post:
      operationId: ListAccessControlConfigurations
      summary: List Access Control Configurations
      description: Lists one or more access control configurations for an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListAccessControlConfigurationsResponse'
        '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.ListAccessControlConfigurations
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListAccessControlConfigurationsRequest'
      tags:
      - Access Control Configuration
  /#UpdateAccessControlConfiguration:
    post:
      operationId: UpdateAccessControlConfiguration
      summary: Update Access Control Configuration
      description: Updates an access control configuration for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can update an access control configuration you created without indexing all of your documents again. For example, your index contains top-secret company documents that only certain employees or users should access. You created an 'allow' access control configuration for one user who recently joined the 'top-secret' team, switching from a team with 'deny' access to top-secret documents. However, the user suddenly returns to their previous team and should no longer have access to top secret documents. You can update the access control configuration to re-configure access control for your documents as circumstances change. You call the BatchPutDocument API to apply the updated access control configuration, with the AccessControlConfigurationId included in the Document object. If you use an S3 bucket as a data source, you synchronize your data source to apply the AccessControlConfigurationId in the .metadata.json fi
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateAccessControlConfigurationResponse'
        '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.UpdateAccessControlConfiguration
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateAccessControlConfigurationRequest'
      tags:
      - Access Control Configuration
components:
  schemas:
    UpdateAccessControlConfigurationRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index for an access control configuration.
        Id:
          type: string
          description: The identifier of the access control configuration you want to update.
        Name:
          type: string
          description: A new name for the access control configuration.
        Description:
          type: string
          description: A new description for the access control configuration.
        AccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: Information you want to update on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
        HierarchicalAccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/HierarchicalPrincipal'
          description: The updated list of principal lists that define the hierarchy for which documents users should have access to.
      required:
      - IndexId
      - Id
    ListAccessControlConfigurationsResponse:
      type: object
      properties:
        NextToken:
          type: string
          description: If the response is truncated, Amazon Kendra returns this token, which you can use in the subsequent request to retrieve the next set of access control configurations.
        AccessControlConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/AccessControlConfigurationSummary'
          description: The details of your access control configurations.
      required:
      - AccessControlConfigurations
    DescribeAccessControlConfigurationRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index for an access control configuration.
        Id:
          type: string
          description: The identifier of the access control configuration you want to get information on.
      required:
      - IndexId
      - Id
    ListAccessControlConfigurationsRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index for the access control configuration.
        NextToken:
          type: string
          description: If the previous response was incomplete (because there's more data to retrieve), Amazon Kendra returns a pagination token in the response. You can use this pagination token to retrieve the next set of access control configurations.
        MaxResults:
          type: integer
          description: The maximum number of access control configurations to return.
      required:
      - IndexId
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    ValidationException:
      type: object
      properties:
        Message:
          type: string
    DeleteAccessControlConfigurationResponse:
      type: object
      properties: {}
    CreateAccessControlConfigurationRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index to create an access control configuration for your documents.
        Name:
          type: string
          description: A name for the access control configuration.
        Description:
          type: string
          description: A description for the access control configuration.
        AccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: Information on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
        HierarchicalAccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/HierarchicalPrincipal'
          description: The list of principal lists that define the hierarchy for which documents users should have access to.
        ClientToken:
          type: string
          description: A token that you provide to identify the request to create an access control configuration. Multiple calls to the CreateAccessControlConfiguration API with the same client token will create only one access control configuration.
      required:
      - IndexId
      - Name
    UpdateAccessControlConfigurationResponse:
      type: object
      properties: {}
    HierarchicalPrincipal:
      type: object
      properties:
        PrincipalList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: A list of principal lists that define the hierarchy for which documents users should have access to. Each hierarchical list specifies which user or group has allow or deny access for each document.
      required:
      - PrincipalList
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
    AccessControlConfigurationSummary:
      type: object
      properties:
        Id:
          type: string
          description: The identifier of the access control configuration.
      required:
      - Id
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
    CreateAccessControlConfigurationResponse:
      type: object
      properties:
        Id:
          type: string
          description: The identifier of the access control configuration for your documents in an index.
      required:
      - Id
    DescribeAccessControlConfigurationResponse:
      type: object
      properties:
        Name:
          type: string
          description: The name for the access control configuration.
        Description:
          type: string
          description: The description for the access control configuration.
        ErrorMessage:
          type: string
          description: The error message containing details if there are issues processing the access control configuration.
        AccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: Information on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
        HierarchicalAccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/HierarchicalPrincipal'
          description: The list of principal lists that define the hierarchy for which documents users should have access to.
      required:
      - Name
    Principal:
      type: object
      properties:
        Name:
          type: string
          description: The name of the user or group.
        Type:
          type: string
          enum:
          - USER
          - GROUP
          description: The type of principal.
        Access:
          type: string
          enum:
          - ALLOW
          - DENY
          description: Whether to allow or deny document access to the principal.
        DataSourceId:
          type: string
          description: The identifier of the data source the principal should access documents from.
      required:
      - Name
      - Type
      - Access
    ConflictException:
      type: object
      properties:
        Message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    DeleteAccessControlConfigurationRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index for an access control configuration.
        Id:
          type: string
          description: The identifier of the access control configuration you want to delete.
      required:
      - IndexId
      - Id
  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)