CubeFS ACLs API

openapi: 3.2.0
info:
  title: CubeFS S3-Compatible AC Ls API
  description: The CubeFS ObjectNode provides an S3-compatible object storage interface that allows applications using AWS S3 SDKs and tools to interact with CubeFS storage without modification. The ObjectNode listens on port 17410 by default and supports standard S3 operations including bucket creation and deletion, object CRUD, multipart uploads, access control lists (ACLs), and pre-signed URL generation. Authentication uses AWS Signature Version 4 with access keys and secret keys managed by the CubeFS Master API.
  version: '3.3'
  contact:
    name: CubeFS Community
    url: https://cubefs.io/community/overview.html
servers:
- url: http://{objectNodeHost}:{objectNodePort}
  description: CubeFS ObjectNode S3-compatible API server
  variables:
    objectNodeHost:
      default: 127.0.0.1
      description: IP address or hostname of the CubeFS ObjectNode.
    objectNodePort:
      default: '17410'
      description: Listening port of the CubeFS ObjectNode.
security:
- awsAuth: []
tags:
- name: ACLs
  description: Access control list operations for buckets and objects. Supports getting and setting ACLs to control access at the bucket and object level.
paths:
  /{bucket}?acl:
    get:
      operationId: getBucketAcl
      summary: CubeFS Get bucket ACL
      description: Returns the access control list for the specified bucket. The ACL defines which accounts or groups have read and write access to the bucket.
      tags:
      - ACLs
      parameters:
      - $ref: '#/components/parameters/bucket'
      responses:
        '200':
          description: Bucket ACL retrieved successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AccessControlPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putBucketAcl
      summary: CubeFS Set bucket ACL
      description: Sets the access control list for the specified bucket. Supports canned ACLs (private, public-read) or a custom ACL with explicit grants.
      tags:
      - ACLs
      parameters:
      - $ref: '#/components/parameters/bucket'
      - name: x-amz-acl
        in: header
        required: false
        description: Canned ACL to apply. Mutually exclusive with request body ACL.
        schema:
          type: string
          enum:
          - private
          - public-read
          - public-read-write
      requestBody:
        required: false
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/AccessControlPolicy'
      responses:
        '200':
          description: Bucket ACL set successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Owner:
      type: object
      description: Owner of a bucket or object.
      properties:
        ID:
          type: string
          description: CubeFS user ID of the owner.
        DisplayName:
          type: string
          description: Display name of the owner.
    S3Error:
      type: object
      description: S3-compatible error response in XML format.
      properties:
        Code:
          type: string
          description: S3 error code such as NoSuchBucket, InvalidBucketName, or BucketNotEmpty.
        Message:
          type: string
          description: Human-readable error message.
        Resource:
          type: string
          description: The bucket or object that the error applies to.
        RequestId:
          type: string
          description: Unique identifier for the request, useful for debugging.
    AccessControlPolicy:
      type: object
      description: Access control policy for a bucket or object.
      properties:
        Owner:
          $ref: '#/components/schemas/Owner'
        AccessControlList:
          type: object
          description: Container for grant entries.
          properties:
            Grant:
              type: array
              description: List of access control grants.
              items:
                $ref: '#/components/schemas/Grant'
    Grantee:
      type: object
      description: An entity to whom access is being granted.
      properties:
        ID:
          type: string
          description: User ID or group identifier.
        DisplayName:
          type: string
          description: Display name of the grantee.
        Type:
          type: string
          description: Type of grantee, typically CanonicalUser or Group.
    Grant:
      type: object
      description: A permission grant in an ACL.
      properties:
        Grantee:
          $ref: '#/components/schemas/Grantee'
        Permission:
          type: string
          enum:
          - FULL_CONTROL
          - READ
          - WRITE
          - READ_ACP
          - WRITE_ACP
          description: Permission level granted.
  parameters:
    bucket:
      name: bucket
      in: path
      required: true
      description: Name of the S3 bucket (corresponds to a CubeFS volume name).
      schema:
        type: string
        minLength: 3
        maxLength: 63
        pattern: ^[a-z0-9][a-z0-9\-]*[a-z0-9]$
  responses:
    NotFound:
      description: The specified bucket or object does not exist.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
    Unauthorized:
      description: Authentication credentials are missing, invalid, or the signature does not match.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
  securitySchemes:
    awsAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'AWS Signature Version 4 authorization. Format: AWS4-HMAC-SHA256 Credential={accessKey}/{date}/{region}/s3/aws4_request, SignedHeaders={headers}, Signature={signature}. Access keys are managed via the CubeFS Master API user management endpoints.'
externalDocs:
  description: CubeFS ObjectNode Documentation
  url: https://cubefs.io/docs/master/user-guide/objectnode.html