Skip to main content

Create an ACL

POST 
/kafka/v3/clusters/:cluster_id/acls

Generally Available

Create an ACL.

Request​

Responses​

Created

OpenAPI definition (YAML) 
paths:
  /kafka/v3/clusters/{cluster_id}/acls:
    post:
      operationId: createKafkaAcls
      description: '[![Generally Available](https://img.shields.io/badge/Lifecycle%20Stage-Generally%20Available-%2345c6e8)](#section/Versioning/API-Lifecycle-Policy)


        Create an ACL.'
      tags:
      - ACL (v3)
      security:
      - resource-api-key: []
      - external-access-token: []
      requestBody:
        description: The ACL creation request.
        content:
          application/json:
            schema:
              type: object
              required:
              - resource_type
              - resource_name
              - pattern_type
              - principal
              - host
              - operation
              - permission
              properties:
                resource_type:
                  type: string
                  enum:
                  - UNKNOWN
                  - ANY
                  - TOPIC
                  - GROUP
                  - CLUSTER
                  - TRANSACTIONAL_ID
                  - DELEGATION_TOKEN
                  title: AclResourceType
                resource_name:
                  type: string
                pattern_type:
                  type: string
                  enum:
                  - UNKNOWN
                  - ANY
                  - MATCH
                  - LITERAL
                  - PREFIXED
                  title: AclPatternType
                principal:
                  type: string
                host:
                  type: string
                operation:
                  type: string
                  enum:
                  - UNKNOWN
                  - ANY
                  - ALL
                  - READ
                  - WRITE
                  - CREATE
                  - DELETE
                  - ALTER
                  - DESCRIBE
                  - CLUSTER_ACTION
                  - DESCRIBE_CONFIGS
                  - ALTER_CONFIGS
                  - IDEMPOTENT_WRITE
                  title: AclOperation
                permission:
                  type: string
                  enum:
                  - UNKNOWN
                  - ANY
                  - DENY
                  - ALLOW
                  title: AclPermission
              title: CreateAclRequestData
            example:
              resource_type: CLUSTER
              resource_name: kafka-cluster
              pattern_type: LITERAL
              principal: principalType:principalName
              host: '*'
              operation: DESCRIBE
              permission: DENY
      responses:
        '201':
          description: Created
        '400':
          description: Indicates a bad request error. It could be caused by an unexpected request body
            format or other forms of request validation failure.
          content:
            application/json:
              schema:
                type: object
                description: Describes a particular error encountered while performing an operation.
                properties:
                  id:
                    description: A unique identifier for this particular occurrence of the problem.
                    type: string
                    maxLength: 255
                  status:
                    description: The HTTP status code applicable to this problem, expressed as a string
                      value.
                    type: string
                  code:
                    description: An application-specific error code, expressed as a string value.
                    type: string
                  title:
                    description: A short, human-readable summary of the problem. It **SHOULD NOT** change
                      from occurrence to occurrence of the problem, except for purposes of localization.
                    type: string
                  detail:
                    description: A human-readable explanation specific to this occurrence of the problem.
                    type: string
                  source:
                    type: object
                    description: If this error was caused by a particular part of the API request, the
                      source will point to the query string parameter or request body property that caused
                      it.
                    properties:
                      pointer:
                        description: A JSON Pointer [RFC6901] to the associated entity in the request
                          document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
                        type: string
                      parameter:
                        description: A string indicating which query parameter caused the error.
                        type: string
                  error_code:
                    type: integer
                    format: int32
                  message:
                    type: string
                    nullable: true
                additionalProperties: false
                title: Error
              examples:
                create_acls_cluster_name_invalid:
                  description: Thrown when creating an ACL for a CLUSTER resource specifying the wrong
                    resource name.
                  value:
                    error_code: 40002
                    message: The only valid name for the CLUSTER resource is kafka-cluster"
        '401':
          description: Indicates a client authentication error. Kafka authentication failures will contain
            error code 40101 in the response body.
          content:
            application/json:
              schema:
                type: object
                description: Describes a particular error encountered while performing an operation.
                properties:
                  id:
                    description: A unique identifier for this particular occurrence of the problem.
                    type: string
                    maxLength: 255
                  status:
                    description: The HTTP status code applicable to this problem, expressed as a string
                      value.
                    type: string
                  code:
                    description: An application-specific error code, expressed as a string value.
                    type: string
                  title:
                    description: A short, human-readable summary of the problem. It **SHOULD NOT** change
                      from occurrence to occurrence of the problem, except for purposes of localization.
                    type: string
                  detail:
                    description: A human-readable explanation specific to this occurrence of the problem.
                    type: string
                  source:
                    type: object
                    description: If this error was caused by a particular part of the API request, the
                      source will point to the query string parameter or request body property that caused
                      it.
                    properties:
                      pointer:
                        description: A JSON Pointer [RFC6901] to the associated entity in the request
                          document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
                        type: string
                      parameter:
                        description: A string indicating which query parameter caused the error.
                        type: string
                  error_code:
                    type: integer
                    format: int32
                  message:
                    type: string
                    nullable: true
                additionalProperties: false
                title: Error
              examples:
                kafka_authentication_failed:
                  description: Thrown when using Basic authentication with wrong Kafka credentials.
                  value:
                    error_code: 40101
                    message: Authentication failed
        '403':
          description: Indicates a client authorization error. Kafka authorization failures will contain
            error code 40301 in the response body.
          content:
            application/json:
              schema:
                type: object
                description: Describes a particular error encountered while performing an operation.
                properties:
                  id:
                    description: A unique identifier for this particular occurrence of the problem.
                    type: string
                    maxLength: 255
                  status:
                    description: The HTTP status code applicable to this problem, expressed as a string
                      value.
                    type: string
                  code:
                    description: An application-specific error code, expressed as a string value.
                    type: string
                  title:
                    description: A short, human-readable summary of the problem. It **SHOULD NOT** change
                      from occurrence to occurrence of the problem, except for purposes of localization.
                    type: string
                  detail:
                    description: A human-readable explanation specific to this occurrence of the problem.
                    type: string
                  source:
                    type: object
                    description: If this error was caused by a particular part of the API request, the
                      source will point to the query string parameter or request body property that caused
                      it.
                    properties:
                      pointer:
                        description: A JSON Pointer [RFC6901] to the associated entity in the request
                          document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
                        type: string
                      parameter:
                        description: A string indicating which query parameter caused the error.
                        type: string
                  error_code:
                    type: integer
                    format: int32
                  message:
                    type: string
                    nullable: true
                additionalProperties: false
                title: Error
              examples:
                kafka_authorization_failed:
                  description: Thrown when the caller is not authorized to perform the underlying operation.
                  value:
                    error_code: 40301
                    message: Request is not authorized
        '429':
          description: Indicates that a rate limit threshold has been reached, and the client should retry
            again later.
          content:
            text/html:
              schema:
                type: string
              example:
                description: A sample response from Jetty's DoSFilter.
                value: <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
                  <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many
                  Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr>
                  <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td>
                  </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>
        5XX:
          description: A server-side problem that might not be addressable from the client side. Retriable
            Kafka errors will contain error code 50003 in the response body.
          content:
            application/json:
              schema:
                type: object
                description: Describes a particular error encountered while performing an operation.
                properties:
                  id:
                    description: A unique identifier for this particular occurrence of the problem.
                    type: string
                    maxLength: 255
                  status:
                    description: The HTTP status code applicable to this problem, expressed as a string
                      value.
                    type: string
                  code:
                    description: An application-specific error code, expressed as a string value.
                    type: string
                  title:
                    description: A short, human-readable summary of the problem. It **SHOULD NOT** change
                      from occurrence to occurrence of the problem, except for purposes of localization.
                    type: string
                  detail:
                    description: A human-readable explanation specific to this occurrence of the problem.
                    type: string
                  source:
                    type: object
                    description: If this error was caused by a particular part of the API request, the
                      source will point to the query string parameter or request body property that caused
                      it.
                    properties:
                      pointer:
                        description: A JSON Pointer [RFC6901] to the associated entity in the request
                          document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
                        type: string
                      parameter:
                        description: A string indicating which query parameter caused the error.
                        type: string
                  error_code:
                    type: integer
                    format: int32
                  message:
                    type: string
                    nullable: true
                additionalProperties: false
                title: Error
              examples:
                generic_internal_server_error:
                  description: Thrown for generic HTTP 500 errors.
                  value:
                    error_code: 500
                    message: Internal Server Error
      parameters:
      - name: cluster_id
        description: The Kafka cluster ID.
        in: path
        required: true
        schema:
          type: string
        example: cluster-1
      servers:
      - url: https://pkc-00000.region.provider.confluent.cloud
        x-audience: business-unit-internal
        description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud
      jsonRequestBodyExample:
        resource_type: UNKNOWN
        resource_name: string
        pattern_type: UNKNOWN
        principal: string
        host: string
        operation: UNKNOWN
        permission: UNKNOWN