openapi: 3.2.0 info: title: Confluent Cloud ACL (v3) API version: '' x-api-id: 46234552-5833-42eb-ba0f-883ad3f70d2b x-audience: external-public x-logo: url: https://assets.confluent.io/m/1661ef5e4ff82d3d/ description: '# Introduction Note This documents the collection of Confluent Cloud APIs.' servers: - url: https://api.confluent.cloud description: Confluent Cloud API tags: - name: ACL (v3) description: '' paths: /kafka/v3/clusters/{cluster_id}/acls:batch: 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 parameters: - $ref: '#/components/parameters/ClusterId' post: summary: Batch Create ACLs operationId: batchCreateKafkaAcls description: ' Create ACLs.' tags: - ACL (v3) security: - resource-api-key: [] - external-access-token: [] requestBody: $ref: '#/components/requestBodies/BatchCreateAclRequest' responses: '201': description: Created '400': $ref: '#/components/responses/BadRequestErrorResponse_CreateAcls' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /kafka/v3/clusters/{cluster_id}/acls: 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 parameters: - $ref: '#/components/parameters/ClusterId' get: summary: List ACLs operationId: getKafkaAcls description: ' - When calling `/acls` without the `principal` parameter, service accounts are returned in numeric ID format (e.g., `User:12345`). - To retrieve service accounts in the `sa-xxx` format, use `/acls?principal=UserV2:*`. - The `principal` parameter supports both legacy `User:` format and new `UserV2:` format for service accounts. Return a list of ACLs that match the search criteria.' tags: - ACL (v3) security: - resource-api-key: [] - external-access-token: [] parameters: - $ref: '#/components/parameters/AclResourceType' - $ref: '#/components/parameters/AclResourceName' - $ref: '#/components/parameters/AclPatternType' - $ref: '#/components/parameters/AclPrincipal' - $ref: '#/components/parameters/AclHost' - $ref: '#/components/parameters/AclOperation' - $ref: '#/components/parameters/AclPermission' responses: '200': $ref: '#/components/responses/SearchAclsResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' post: summary: Create an ACL operationId: createKafkaAcls description: ' Create an ACL.' tags: - ACL (v3) security: - resource-api-key: [] - external-access-token: [] requestBody: $ref: '#/components/requestBodies/CreateAclRequest' responses: '201': description: Created '400': $ref: '#/components/responses/BadRequestErrorResponse_CreateAcls' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' delete: summary: Delete ACLs operationId: deleteKafkaAcls description: ' Delete the ACLs that match the search criteria.' tags: - ACL (v3) security: - resource-api-key: [] - external-access-token: [] parameters: - $ref: '#/components/parameters/AclResourceTypeRequired' - $ref: '#/components/parameters/AclResourceName' - $ref: '#/components/parameters/AclPatternTypeRequired' - $ref: '#/components/parameters/AclPrincipal' - $ref: '#/components/parameters/AclHost' - $ref: '#/components/parameters/AclOperationRequired' - $ref: '#/components/parameters/AclPermissionRequired' responses: '200': $ref: '#/components/responses/DeleteAclsResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse_DeleteAcls' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' components: parameters: AclPrincipal: name: principal description: 'The ACL principal. This is the Service Account name or user name. Supports both legacy `User:` format (numeric IDs) and new `UserV2:` format (sa-xxx format) for service accounts. Use `UserV2:*` to retrieve service accounts in the new format.' in: query required: false schema: type: string AclPatternTypeRequired: name: pattern_type description: The ACL pattern type. in: query required: true schema: $ref: '#/components/schemas/AclPatternType' AclPermission: name: permission description: The ACL permission. in: query required: false schema: $ref: '#/components/schemas/AclPermission' AclResourceTypeRequired: name: resource_type description: The ACL resource type. in: query required: true schema: $ref: '#/components/schemas/AclResourceType' AclPermissionRequired: name: permission description: The ACL permission. in: query required: true schema: $ref: '#/components/schemas/AclPermission' ClusterId: name: cluster_id description: The Kafka cluster ID. in: path required: true schema: type: string example: cluster-1 AclOperation: name: operation description: The ACL operation. in: query required: false schema: $ref: '#/components/schemas/AclOperation' AclResourceType: name: resource_type description: The ACL resource type. in: query required: false schema: $ref: '#/components/schemas/AclResourceType' AclHost: name: host description: The ACL host. in: query required: false schema: type: string AclPatternType: name: pattern_type description: The ACL pattern type. in: query required: false schema: $ref: '#/components/schemas/AclPatternType' AclOperationRequired: name: operation description: The ACL operation. in: query required: true schema: $ref: '#/components/schemas/AclOperation' AclResourceName: name: resource_name description: The ACL resource name. in: query required: false schema: type: string schemas: Error: 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 - 'null' additionalProperties: false AclPermission: type: string x-extensible-enum: - UNKNOWN - ANY - DENY - ALLOW AclResourceType: type: string enum: - UNKNOWN - ANY - TOPIC - GROUP - CLUSTER - TRANSACTIONAL_ID - DELEGATION_TOKEN AclPatternType: type: string x-extensible-enum: - UNKNOWN - ANY - MATCH - LITERAL - PREFIXED AclDataList: allOf: - $ref: '#/components/schemas/ResourceCollection' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/AclData' AclOperation: type: string x-extensible-enum: - UNKNOWN - ANY - ALL - READ - WRITE - CREATE - DELETE - ALTER - DESCRIBE - CLUSTER_ACTION - DESCRIBE_CONFIGS - ALTER_CONFIGS - IDEMPOTENT_WRITE ResourceCollectionMetadata: type: object required: - self properties: self: type: string next: type: - string - 'null' Resource: type: object required: - kind - metadata properties: kind: type: string metadata: $ref: '#/components/schemas/ResourceMetadata' CreateAclRequestData: type: object required: - resource_type - resource_name - pattern_type - principal - host - operation - permission properties: resource_type: $ref: '#/components/schemas/AclResourceType' resource_name: type: string pattern_type: $ref: '#/components/schemas/AclPatternType' principal: type: string host: type: string operation: $ref: '#/components/schemas/AclOperation' permission: $ref: '#/components/schemas/AclPermission' CreateAclRequestDataList: allOf: - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/CreateAclRequestData' AclData: allOf: - $ref: '#/components/schemas/Resource' - type: object required: - cluster_id - resource_type - resource_name - pattern_type - principal - host - operation - permission properties: cluster_id: type: string resource_type: $ref: '#/components/schemas/AclResourceType' resource_name: type: string pattern_type: $ref: '#/components/schemas/AclPatternType' principal: type: string host: type: string operation: $ref: '#/components/schemas/AclOperation' permission: $ref: '#/components/schemas/AclPermission' ResourceCollection: type: object required: - kind - metadata properties: kind: type: string metadata: $ref: '#/components/schemas/ResourceCollectionMetadata' ResourceMetadata: type: object required: - self properties: self: type: string resource_name: type: - string - 'null' responses: ForbiddenErrorResponse: description: Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body. content: application/json: schema: $ref: '#/components/schemas/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 BadRequestErrorResponse_CreateAcls: 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: $ref: '#/components/schemas/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" BadRequestErrorResponse: 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: $ref: '#/components/schemas/Error' examples: bad_request_cannot_deserialize: description: Thrown when trying to deserialize an integer from non-integer data. value: error_code: 400 message: 'Cannot deserialize value of type `java.lang.Integer` from String "A": not a valid `java.lang.Integer` value' unsupported_version_exception: description: Thrown when the version of this API is not supported in the underlying Kafka cluster. value: error_code: 40035 message: The version of this API is not supported in the underlying Kafka cluster. UnauthorizedErrorResponse: description: Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body. content: application/json: schema: $ref: '#/components/schemas/Error' examples: kafka_authentication_failed: description: Thrown when using Basic authentication with wrong Kafka credentials. value: error_code: 40101 message: Authentication failed SearchAclsResponse: description: The list of ACLs. content: application/json: schema: $ref: '#/components/schemas/AclDataList' example: kind: KafkaAclList metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?principal=User%3Aalice data: - kind: KafkaAcl metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=TOPIC&resource_name=topic-&pattern_type=PREFIXED&principal=User%3Aalice&host=*&operation=ALL&permission=ALLOW cluster_id: cluster-1 resource_type: TOPIC resource_name: topic- pattern_type: PREFIXED principal: User:alice host: '*' operation: ALL permission: ALLOW - kind: KafkaAcl metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=CLUSTER&resource_name=kafka-cluster&pattern_type=LITERAL&principal=User%3Aalice&host=*&operation=DESCRIBE&permission=DENY cluster_id: cluster-1 resource_type: CLUSTER resource_name: kafka-cluster pattern_type: LITERAL principal: User:alice host: '*' operation: DESCRIBE permission: DENY TooManyRequestsErrorResponse: 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:
| URI: | /v3/clusters/my-cluster |
|---|---|
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |