Amazon S3 Bucket Configuration API

openapi: 3.1.0
info:
  title: Amazon S3 Control Access Control Bucket Configuration API
  description: Amazon S3 Control provides API operations for managing S3 account-level settings, access points, Batch Operations jobs, S3 Access Grants, Multi-Region Access Points, and Storage Lens configurations. The S3 Control API uses a separate endpoint from the standard S3 API and requires an account ID in the host header.
  version: '2018-08-20'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/premiumsupport/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://aws.amazon.com/service-terms/
  x-logo:
    url: https://a0.awsstatic.com/libra-css/images/logos/aws_logo_smile_1200x630.png
servers:
- url: https://s3-control.{region}.amazonaws.com
  description: Amazon S3 Control regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-north-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-southeast-1
      - ap-southeast-2
      - ap-south-1
      - sa-east-1
      - ca-central-1
security:
- sigv4: []
tags:
- name: Bucket Configuration
  description: Operations for managing bucket-level configuration such as versioning, lifecycle, CORS, and encryption
paths:
  /{Bucket}?versioning:
    get:
      operationId: GetBucketVersioning
      summary: Amazon S3 Get Bucket Versioning
      description: Returns the versioning state of a bucket. To retrieve the versioning state of a bucket, you must be the bucket owner. This implementation also returns the MFA Delete status of a bucket.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned versioning configuration.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/VersioningConfiguration'
              examples:
                Getbucketversioning200Example:
                  summary: Default GetBucketVersioning 200 response
                  x-microcks-default: true
                  value:
                    Status: Enabled
                    MFADelete: Enabled
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketversioning403Example:
                  summary: Default GetBucketVersioning 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: PutBucketVersioning
      summary: Amazon S3 Put Bucket Versioning
      description: Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner. You can set the versioning state to Enabled or Suspended.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: Content-MD5
        in: header
        description: The base64-encoded 128-bit MD5 digest of the data.
        schema:
          type: string
        example: example_value
      - name: x-amz-mfa
        in: header
        description: The concatenation of the authentication device serial number, a space, and the value displayed on your authentication device.
        schema:
          type: string
        example: example_value
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/VersioningConfiguration'
            examples:
              PutbucketversioningRequestExample:
                summary: Default PutBucketVersioning request
                x-microcks-default: true
                value:
                  Status: Enabled
                  MFADelete: Enabled
      responses:
        '200':
          description: Versioning configuration updated successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Putbucketversioning403Example:
                  summary: Default PutBucketVersioning 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{Bucket}?encryption:
    get:
      operationId: GetBucketEncryption
      summary: Amazon S3 Get Bucket Encryption
      description: Returns the default encryption configuration for an Amazon S3 bucket. By default, all buckets have a default encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3).
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned encryption configuration.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ServerSideEncryptionConfiguration'
              examples:
                Getbucketencryption200Example:
                  summary: Default GetBucketEncryption 200 response
                  x-microcks-default: true
                  value:
                    Rule:
                    - ApplyServerSideEncryptionByDefault:
                        SSEAlgorithm: AES256
                        KMSMasterKeyID: '500123'
                      BucketKeyEnabled: true
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketencryption403Example:
                  summary: Default GetBucketEncryption 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: PutBucketEncryption
      summary: Amazon S3 Put Bucket Encryption
      description: This action uses the encryption subresource to configure default encryption and Amazon S3 Bucket Keys for an existing bucket.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: Content-MD5
        in: header
        description: The base64-encoded 128-bit MD5 digest.
        schema:
          type: string
        example: example_value
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      - name: x-amz-checksum-algorithm
        in: header
        description: Algorithm used to create the checksum.
        schema:
          type: string
          enum:
          - CRC32
          - CRC32C
          - SHA1
          - SHA256
        example: CRC32
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/ServerSideEncryptionConfiguration'
            examples:
              PutbucketencryptionRequestExample:
                summary: Default PutBucketEncryption request
                x-microcks-default: true
                value:
                  Rule:
                  - ApplyServerSideEncryptionByDefault:
                      SSEAlgorithm: AES256
                      KMSMasterKeyID: '500123'
                    BucketKeyEnabled: true
      responses:
        '200':
          description: Encryption configuration updated successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Putbucketencryption403Example:
                  summary: Default PutBucketEncryption 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: DeleteBucketEncryption
      summary: Amazon S3 Delete Bucket Encryption
      description: This implementation of the DELETE action resets the default encryption for the bucket as server-side encryption with Amazon S3 managed keys (SSE-S3).
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: Encryption configuration deleted successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deletebucketencryption403Example:
                  summary: Default DeleteBucketEncryption 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{Bucket}?lifecycle:
    get:
      operationId: GetBucketLifecycleConfiguration
      summary: Amazon S3 Get Bucket Lifecycle Configuration
      description: Returns the lifecycle configuration information set on the bucket. It returns the lifecycle configuration for the specified bucket or an error if the lifecycle configuration does not exist.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned lifecycle configuration.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/BucketLifecycleConfiguration'
              examples:
                Getbucketlifecycleconfiguration200Example:
                  summary: Default GetBucketLifecycleConfiguration 200 response
                  x-microcks-default: true
                  value:
                    Rule:
                    - ID: abc123
                      Filter: {}
                      Status: Enabled
                      Expiration: {}
                      Transition: {}
                      NoncurrentVersionExpiration: {}
                      NoncurrentVersionTransition: {}
                      AbortIncompleteMultipartUpload: {}
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketlifecycleconfiguration403Example:
                  summary: Default GetBucketLifecycleConfiguration 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '404':
          description: The lifecycle configuration does not exist.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketlifecycleconfiguration404Example:
                  summary: Default GetBucketLifecycleConfiguration 404 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: PutBucketLifecycleConfiguration
      summary: Amazon S3 Put Bucket Lifecycle Configuration
      description: Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. Lifecycle configuration manages objects so that they are stored cost effectively throughout their lifecycle.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      - name: x-amz-checksum-algorithm
        in: header
        description: Algorithm used to create the checksum.
        schema:
          type: string
          enum:
          - CRC32
          - CRC32C
          - SHA1
          - SHA256
        example: CRC32
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/BucketLifecycleConfiguration'
            examples:
              PutbucketlifecycleconfigurationRequestExample:
                summary: Default PutBucketLifecycleConfiguration request
                x-microcks-default: true
                value:
                  Rule:
                  - ID: abc123
                    Filter: {}
                    Status: Enabled
                    Expiration: {}
                    Transition: {}
                    NoncurrentVersionExpiration: {}
                    NoncurrentVersionTransition: {}
                    AbortIncompleteMultipartUpload: {}
      responses:
        '200':
          description: Lifecycle configuration updated successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Putbucketlifecycleconfiguration403Example:
                  summary: Default PutBucketLifecycleConfiguration 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: DeleteBucketLifecycle
      summary: Amazon S3 Delete Bucket Lifecycle
      description: Deletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: Lifecycle configuration deleted successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deletebucketlifecycle403Example:
                  summary: Default DeleteBucketLifecycle 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{Bucket}?cors:
    get:
      operationId: GetBucketCors
      summary: Amazon S3 Get Bucket Cors
      description: Returns the Cross-Origin Resource Sharing (CORS) configuration information set for the bucket. To use this operation, you must have permission to perform the s3:GetBucketCORS action.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned CORS configuration.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CORSConfiguration'
              examples:
                Getbucketcors200Example:
                  summary: Default GetBucketCors 200 response
                  x-microcks-default: true
                  value:
                    CORSRule:
                    - ID: abc123
                      AllowedHeaders:
                      - {}
                      AllowedMethods:
                      - {}
                      AllowedOrigins:
                      - {}
                      ExposeHeaders:
                      - {}
                      MaxAgeSeconds: 10
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketcors403Example:
                  summary: Default GetBucketCors 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '404':
          description: CORS configuration does not exist.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getbucketcors404Example:
                  summary: Default GetBucketCors 404 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: PutBucketCors
      summary: Amazon S3 Put Bucket Cors
      description: Sets the CORS configuration for your bucket. If the configuration exists, Amazon S3 replaces it. To use this operation, you must be allowed to perform the s3:PutBucketCORS action.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: Content-MD5
        in: header
        description: The base64-encoded 128-bit MD5 digest.
        schema:
          type: string
        example: example_value
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CORSConfiguration'
            examples:
              PutbucketcorsRequestExample:
                summary: Default PutBucketCors request
                x-microcks-default: true
                value:
                  CORSRule:
                  - ID: abc123
                    AllowedHeaders:
                    - {}
                    AllowedMethods:
                    - {}
                    AllowedOrigins:
                    - {}
                    ExposeHeaders:
                    - {}
                    MaxAgeSeconds: 10
      responses:
        '200':
          description: CORS configuration updated successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Putbucketcors403Example:
                  summary: Default PutBucketCors 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: DeleteBucketCors
      summary: Amazon S3 Delete Bucket Cors
      description: Deletes the CORS configuration information set for the bucket.
      tags:
      - Bucket Configuration
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: CORS configuration deleted successfully.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deletebucketcors403Example:
                  summary: Default DeleteBucketCors 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    VersioningConfiguration:
      type: object
      description: Container for setting the versioning state.
      xml:
        name: VersioningConfiguration
        namespace: http://s3.amazonaws.com/doc/2006-03-01/
      properties:
        Status:
          type: string
          description: The versioning state of the bucket.
          enum:
          - Enabled
          - Suspended
          example: Enabled
        MFADelete:
          type: string
          description: Specifies whether MFA delete is enabled in the bucket versioning configuration.
          enum:
          - Enabled
          - Disabled
          example: Enabled
    BucketLifecycleConfiguration:
      type: object
      description: Container for lifecycle rules.
      xml:
        name: LifecycleConfiguration
        namespace: http://s3.amazonaws.com/doc/2006-03-01/
      required:
      - Rule
      properties:
        Rule:
          type: array
          items:
            $ref: '#/components/schemas/LifecycleRule'
          example: []
    CORSConfiguration:
      type: object
      description: Describes the cross-origin access configuration for objects in an Amazon S3 bucket.
      xml:
        name: CORSConfiguration
        namespace: http://s3.amazonaws.com/doc/2006-03-01/
      required:
      - CORSRule
      properties:
        CORSRule:
          type: array
          items:
            type: object
            required:
            - AllowedMethods
            - AllowedOrigins
            properties:
              ID:
                type: string
              AllowedHeaders:
                type: array
                items:
                  type: string
              AllowedMethods:
                type: array
                items:
                  type: string
                  enum:
                  - GET
                  - PUT
                  - HEAD
                  - POST
                  - DELETE
              AllowedOrigins:
                type: array
                items:
                  type: string
              ExposeHeaders:
                type: array
                items:
                  type: string
              MaxAgeSeconds:
                type: integer
          example: []
    LifecycleRule:
      type: object
      description: A lifecycle rule for individual objects in an Amazon S3 bucket.
      required:
      - Status
      properties:
        ID:
          type: string
          description: Unique identifier for the rule.
          example: abc123
        Filter:
          type: object
          description: The filter used to identify objects for the rule.
          properties:
            Prefix:
              type: string
            Tag:
              $ref: '#/components/schemas/Tag'
            And:
              type: object
              properties:
                Prefix:
                  type: string
                Tags:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tag'
                ObjectSizeGreaterThan:
                  type: integer
                  format: int64
                ObjectSizeLessThan:
                  type: integer
                  format: int64
            ObjectSizeGreaterThan:
              type: integer
              format: int64
            ObjectSizeLessThan:
              type: integer
              format: int64
          example: example_value
        Status:
          type: string
          description: If Enabled, Amazon S3 executes the lifecycle actions. If Disabled, Amazon S3 ignores the lifecycle actions.
          enum:
          - Enabled
          - Disabled
          example: Enabled
        Expiration:
          type: object
          properties:
            Date:
              type: string
              format: date-time
            Days:
              type: integer
            ExpiredObjectDeleteMarker:
              type: boolean
          example: example_value
        Transition:
          type: array
          items:
            type: object
            properties:
              Date:
                type: string
                format: date-time
              Days:
                type: integer
              StorageClass:
                type: string
                enum:
                - GLACIER
                - STANDARD_IA
                - ONEZONE_IA
                - INTELLIGENT_TIERING
                - DEEP_ARCHIVE
                - GLACIER_IR
          example: []
        NoncurrentVersionExpiration:
          type: object
          properties:
            NoncurrentDays:
              type: integer
            NewerNoncurrentVersions:
              type: integer
          example: example_value
        NoncurrentVersionTransition:
          type: array
          items:
            type: object
            properties:
              NoncurrentDays:
                type: integer
              StorageClass:
                type: string
              NewerNoncurrentVersions:
                type: integer
          example: []
        AbortIncompleteMultipartUpload:
          type: object
          properties:
            DaysAfterInitiation:
              type: integer
          example: example_value
    ServerSideEncryptionConfiguration:
      type: object
      description: Specifies the default server-side-encryption configuration.
      xml:
        name: ServerSideEncryptionConfiguration
        namespace: http://s3.amazonaws.com/doc/2006-03-01/
      required:
      - Rule
      properties:
        Rule:
          type: array
          items:
            type: object
            properties:
              ApplyServerSideEncryptionByDefault:
                type: object
                properties:
                  SSEAlgorithm:
                    type: string
                    description: Server-side encryption algorithm to use for the default encryption.
                    enum:
                    - AES256
                    - aws:kms
                    - aws:kms:dsse
                  KMSMasterKeyID:
                    type: string
                    description: AWS Key Management Service (KMS) customer managed key ID to use for the default encryption.
              BucketKeyEnabled:
                type: boolean
                description: Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS).
          example: []
    Error:
      type: object
      description: Container for all error elements.
      xml:
        name: Error
      properties:
        Code:
          type: string
          description: The error code is a string that uniquely identifies an error condition. Examples include NoSuchBucket, NoSuchKey, AccessDenied, InvalidBucketName, etc.
          example: example_value
        Message:
          type: string
          description: A human-readable description of the error.
          example: example_value
        Resource:
          type: string
          description: The bucket or object that is involved in the error.
          example: example_value
        RequestId:
          type: string
          description: Unique identifier for the request.
          example: '500123'
        HostId:
          type: string
          description: A special token to help AWS troubleshoot problems.
          example: '500123'
    Tag:
      type: object
      description: A container of a key value name pair.
      required:
      - Key
      - Value
      properties:
        Key:
          type: string
          description: Name of the object key.
          minLength: 1
          maxLength: 128
          example: example_value
        Value:
          type: string
          description: Value of the tag.
          maxLength: 256
          example: example_value
  parameters:
    BucketName:
      name: Bucket
      in: path
      required: true
      description: The name of the bucket. Bucket names must be between 3 and 63 characters long, consist only of lowercase letters, numbers, hyphens, and periods, and must begin and end with a letter or number.
      schema:
        type: string
        minLength: 3
        maxLength: 63
        pattern: ^[a-z0-9][a-z0-9.\-]{1,61}[a-z0-9]$
  securitySchemes:
    sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication. The S3 Control API uses the service name s3 for signing.
externalDocs:
  description: Amazon S3 Control API Reference
  url: https://docs.aws.amazon.com/AmazonS3/latest/API/API_Types_AWS_S3_Control.html