List ACLs
GET/kafka/v3/clusters/:cluster_id/acls
- When calling
/aclswithout theprincipalparameter, service accounts are returned in numeric ID format (e.g.,User:12345). - To retrieve service accounts in the
sa-xxxformat, use/acls?principal=UserV2:*. - The
principalparameter supports both legacyUser:format and newUserV2:format for service accounts. Return a list of ACLs that match the search criteria.
Request
Responses
- 200
- 400
- 401
- 403
- 429
- 5XX
The list of ACLs.
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
Indicates that a rate limit threshold has been reached, and the client should retry again later.
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.
OpenAPI definition (YAML)
paths:
/kafka/v3/clusters/{cluster_id}/acls:
get:
operationId: getKafkaAcls
description: "[](#section/Versioning/API-Lifecycle-Policy)\n\
- When calling `/acls` without the `principal` parameter, service\n accounts are returned in\
\ numeric ID format (e.g., `User:12345`).\n- To retrieve service accounts in the `sa-xxx` format,\
\ use\n `/acls?principal=UserV2:*`.\n- The `principal` parameter supports both legacy `User:`\
\ format and\n new `UserV2:` format for service accounts.\nReturn a list of ACLs that match the\
\ search criteria."
tags:
- ACL (v3)
security:
- resource-api-key: []
- external-access-token: []
parameters:
- name: resource_type
description: The ACL resource type.
in: query
required: false
schema:
type: string
enum:
- UNKNOWN
- ANY
- TOPIC
- GROUP
- CLUSTER
- TRANSACTIONAL_ID
- DELEGATION_TOKEN
title: AclResourceType
- name: resource_name
description: The ACL resource name.
in: query
required: false
schema:
type: string
- name: pattern_type
description: The ACL pattern type.
in: query
required: false
schema:
type: string
enum:
- UNKNOWN
- ANY
- MATCH
- LITERAL
- PREFIXED
title: AclPatternType
- 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
- name: host
description: The ACL host.
in: query
required: false
schema:
type: string
- name: operation
description: The ACL operation.
in: query
required: false
schema:
type: string
enum:
- UNKNOWN
- ANY
- ALL
- READ
- WRITE
- CREATE
- DELETE
- ALTER
- DESCRIBE
- CLUSTER_ACTION
- DESCRIBE_CONFIGS
- ALTER_CONFIGS
- IDEMPOTENT_WRITE
title: AclOperation
- name: permission
description: The ACL permission.
in: query
required: false
schema:
type: string
enum:
- UNKNOWN
- ANY
- DENY
- ALLOW
title: AclPermission
- name: cluster_id
description: The Kafka cluster ID.
in: path
required: true
schema:
type: string
example: cluster-1
responses:
'200':
description: The list of ACLs.
content:
application/json:
schema:
allOf:
- type: object
required:
- kind
- metadata
properties:
kind:
type: string
metadata:
type: object
required:
- self
properties:
self:
type: string
next:
type: string
nullable: true
title: ResourceCollectionMetadata
title: ResourceCollection
- type: object
required:
- data
properties:
data:
type: array
items:
allOf:
- type: object
required:
- kind
- metadata
properties:
kind:
type: string
metadata:
type: object
required:
- self
properties:
self:
type: string
resource_name:
type: string
nullable: true
title: ResourceMetadata
title: Resource
- type: object
required:
- cluster_id
- resource_type
- resource_name
- pattern_type
- principal
- host
- operation
- permission
properties:
cluster_id:
type: string
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: AclData
title: 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
'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:
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.
'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
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