Confluent Metadata API Reference

The Confluent Metadata API has many endpoints, conceptually grouped as follows:

Authentication

Authenticates users against LDAP and returns user bearer tokens that can be used with the other MDS endpoints and components in Confluent Platform (when configured to do so).

Authorization

Authorizes users to perform specific actions. Clients are not expected to use these endpoints, which are used by Confluent Platform components (such as Connect and ksqlDB) to authorize user actions.

Role Based Access Control

  • Role binding CRUD
  • Role binding summaries (used by Confluent CLI)
  • High-level role binding management and rollups (used by Confluent Control Center)

Centralized ACL Control

  • With Authorization using centralized ACLs Confluent Platform provides the option to store ACLs in Kafka instead of ZooKeeper
  • ACL CRUD for legacy Kafka-managed and centralized MDS-based ACLs

Access Restrictions

Some endpoints can be called by any authenticated user, while others can only be called by “admins”. Additionally, many of the endpoints in the API involve two users: the user who is calling the endpoint (the “calling” principal) and the user that the API call is about (the “target” principal).

Example: User “alice”, who has the UserAdmin role, and is identified by her basic auth credentials or a bearer token, calls the CRUD endpoint to modify role bindings about user “bob”.

To document what access restrictions each endpoint has, use the following legend, which lists access in order from least restrictive to most restrictive:

LDAP
Any authenticated LDAP user
Admins+User
Admins or users requesting information about themselves
Admins+ResourceOwners
Admins or users with ResourceOwner role
Admins+AclUsers
Admins or the user having the required ACL permissions
Admins
Admins only, which can be UserAdmin, SystemAdmin, broker super.user, or SecurityAdmin as “Read”

Overview of Responses

Valid Responses

  • 200: Successful call with a return body.
  • 204: Successful call with no return body.

Errors

  • 400: Invalid request. JSON parsing error, or otherwise incorrect request.
  • 401: Not Authenticated. You need to pass valid basic auth credentials or a user bearer token.
  • 403: Not Authorized. Valid request, but you aren’t authorized to perform the requested action.
  • 404: Invalid URL. If you get this error from the authenticate endpoint, it means bearer token authentication needs to be enabled in the configuration (confluent.metadata.server.authentication.method=BEARER)
  • 405: Method Not Allowed. Using the wrong HTTP method on a valid endpoint (for example, GET instead of POST).
  • 415: Invalid Content Type. Usually, not sending “application/json” as request body header.
  • 500: Server Error.

Special Resource Types

Cluster and KsqlCluster are special ResourceTypes because they grant resource-scoped roles like ResourceOwner and DeveloperManage limited access to cluster-level operations (for example, Describe Configs on Kafka clusters). These special resource types only accept LITERAL patterns with the values kafka-cluster and ksql-cluster, respectively.

Exploring the API

The Metadata Service ships with an OpenAPI spec which can be explored and interacted with using an embedded Swagger UI.

To enable the embedded Swagger UI, add the following to the broker’s config when also configuring the Metadata Service. confluent.metadata.server.openapi.enable=true

This will make the Swagger UI available on the broker as http://<host>:<port>/security/openapi/swagger-ui/index.html.

Warning

The Swagger UI and the Open API spec file are provided for development and test purposes only:

  • Do not enable in production environments.
  • The Swagger UI works only with HTTP.

Private RBAC UI Endpoints

These endpoints were developed specifically to power the Confluent Control Center UI. As such, they only focus on those use cases and have only been tested in the context of Confluent Control Center. These endpoints have not been tested, nor has their usability been evaluated with respect to manual API calls.

API Endpoints

1 - Tokens & Authentication

GET /authenticate

Get a token. Callable by LDAP users.

Status Codes:
  • 200 OK

    authenticated

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "auth_token": "string",
        "token_type": "string",
        "expires_in": 1.0
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

2 - Authorization

PUT /authorize

Authorize operations against resourceType for a given user. Callable by Admins+User.

Example request:

PUT /authorize HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "userPrincipal": "User:bob",
    "actions": [
        {
            "scope": {
                "clusters": {
                    "kafka-cluster": "K_GUID"
                }
            },
            "resourceName": "clicksTopic1",
            "resourceType": "Topic",
            "operation": "Read"
        }
    ]
}
Status Codes:
  • 200 OK

    2 - Authorization proccessed

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "ALLOWED",
        "DENIED"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

3 - Metadata Service Operations

GET /activenodes/{protocol}

Returns all the nodes running the Metadata Service REST API. Clients are expected to round robin call to these endpoints if they don’t set up a load balancer in front of the Metadata Service nodes. Callable by LDAP users.

Parameters:
  • protocol (string) – Should be “http” or “https”.
Status Codes:
  • 200 OK

    List of other nodes running the Metadata Service.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "http://10.10.10.50:8090",
        "http://10.10.10.51:8090"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
GET /metadataClusterId

Returns the ID of the Kafka cluster that MDS is running on. Callable by LDAP users.

Status Codes:
  • 200 OK

    Lists other nodes running the Metadata Service.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    ENZ7FS8uTQOhXElRiE-L7g
    

4 - RBAC - Role Definitions

GET /roles

Returns all the roles defined in the system. For information and developer purposes. Callable by LDAP users.

Status Codes:
  • 200 OK

    List of roles with resourceType and allowed operations.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "accessPolicy": {
                "scopeType": "string",
                "allowedOperations": [
                    {
                        "resourceType": "string",
                        "operations": [
                            "string"
                        ]
                    }
                ]
            }
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
GET /roles/{roleName}

List the resourceType and operations allowed for a given role. Callable by LDAP users.

Parameters:
  • roleName (string) – Role name to look up.
Status Codes:
  • 200 OK

    A single role.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "accessPolicy": {
            "scopeType": "string",
            "allowedOperations": [
                {
                    "resourceType": "string",
                    "operations": [
                        "string"
                    ]
                }
            ]
        }
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
GET /roleNames

Returns the names of all the roles defined in the system. For information and developer purposes. Callable by LDAP users.

Status Codes:
  • 200 OK

    The names of the roles defined in the system.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "string"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

5 - RBAC - RoleBinding CRUD

POST /principals/{principal}/roles/{roleName}

Binds the principal to a cluster-scoped role for a specific cluster or in the given scope. Callable by Admins.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the cluster-scoped role to bind the user to.

Example request:

POST /principals/{principal}/roles/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 204 No Content – Role Granted
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
DELETE /principals/{principal}/roles/{roleName}

Remove the role (cluster or resource scoped) from the principal at the given scope/cluster. No-op if the user doesn’t have the role. Callable by Admins.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the role.

Example request:

DELETE /principals/{principal}/roles/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 204 No Content – Role removal processed.
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /principals/{principal}/roles/{roleName}/resources

Look up the rolebindings for the principal at the given scope/cluster using the given role. Callable by Admins.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the role.

Example request:

POST /principals/{principal}/roles/{roleName}/resources HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    Granted

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "resourceType": "Topic",
            "name": "clicksTopic1",
            "patternType": "LITERAL"
        },
        {
            "resourceType": "Topic",
            "name": "orders-2019",
            "patternType": "PREFIXED"
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /principals/{principal}/roles/{roleName}/bindings

Incrementally grant the resources to the principal at the given scope/cluster using the given role. Callable by Admins+ResourceOwners.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the role.

Example request:

POST /principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string"
        }
    },
    "resourcePatterns": [
        {
            "resourceType": "string",
            "name": "string",
            "patternType": "string"
        }
    ]
}
Status Codes:
  • 204 No Content – Granted
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
DELETE /principals/{principal}/roles/{roleName}/bindings

Incrementally remove the resources from the principal at the given scope/cluster using the given role. Callable by Admins+ResourceOwners.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the role.

Example request:

DELETE /principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string"
        }
    },
    "resourcePatterns": [
        {
            "resourceType": "string",
            "name": "string",
            "patternType": "string"
        }
    ]
}
Status Codes:
  • 204 No Content – Resources Removed
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
PUT /principals/{principal}/roles/{roleName}/bindings

Overwrite existing resource grants. Callable by Admins+ResourceOwners.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • roleName (string) – The name of the role.

Example request:

PUT /principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string"
        }
    },
    "resourcePatterns": [
        {
            "resourceType": "string",
            "name": "string",
            "patternType": "string"
        }
    ]
}
Status Codes:
  • 204 No Content – Resources Set
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

6 - RBAC - RoleBinding Summaries

POST /lookup/principals/{principal}/roleNames

Returns the effective list of role names for a principal. For groups, these are the roles that are bound. For users, this is the combination of roles granted to the specific user and roles granted to the user’s groups. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.

Example request:

POST /lookup/principals/{principal}/roleNames HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    List of role names.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "Cluster Admin",
        "Security Admin"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /lookup/principal/{principal}/resources

Look up the resource bindings for the principal at the given scope/cluster. Includes bindings from groups that the user belongs to. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.

Example request:

POST /lookup/principal/{principal}/resources HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    Nested map of principal-to-role-to-resources.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "User:alice": {
            "DeveloperRead": [
                {
                    "resourceType": "Topic",
                    "name": "billing-invoices",
                    "patternType": "LITERAL"
                }
            ]
        },
        "Group:Investors": {
            "DeveloperRead": [
                {
                    "resourceType": "Topic",
                    "name": "investing-",
                    "patternType": "PREFIXED"
                }
            ]
        }
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /lookup/role/{roleName}

Look up the KafkaPrincipals who have the given role for the given scope. Callable by Admins.

Parameters:
  • roleName (string) – Role name to look up.

Example request:

POST /lookup/role/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    List of fully-qualified KafkaPrincipals.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "User:alice",
        "Group:FinanceAdmin"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /lookup/role/{roleName}/resource/{resourceType}/name/{resourceName}

Look up the KafkaPrincipals who have the given role on the specified resource for the given scope. Callable by Admins.

Parameters:
  • roleName (string) – Role name to look up.
  • resourceType (string) – Type of resource to look up.
  • resourceName (string) – Name of resource to look up.

Example request:

POST /lookup/role/{roleName}/resource/{resourceType}/name/{resourceName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    List of fully-qualified KafkaPrincipals.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "User:alice",
        "Group:FinanceAdmin"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

7 - Kafka ACL Management

POST /acls

Creates Kafka ACLs for given AclBinding. Callable by Admins+AclUsers.

Example request:

POST /acls HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string"
        }
    },
    "aclBinding": {
        "pattern": {
            "resourceType": "UNKNOWN",
            "name": "string",
            "patternType": "UNKNOWN"
        },
        "entry": {
            "principal": "string",
            "host": "string",
            "operation": "UNKNOWN",
            "permissionType": "UNKNOWN"
        }
    }
}
Status Codes:
  • 204 No Content – Added AclBinding.
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
DELETE /acls

Deletes Kafka ACLs according to the supplied filter. Callable by Admins+AclUsers.

Example request:

DELETE /acls HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string"
        }
    },
    "aclBindingFilter": {
        "patternFilter": {
            "resourceType": "UNKNOWN",
            "name": "string",
            "patternType": "UNKNOWN"
        },
        "entryFilter": {
            "principal": "string",
            "host": "string",
            "operation": "UNKNOWN",
            "permissionType": "UNKNOWN"
        }
    }
}
Status Codes:
  • 200 OK

    Deleted AclBindings.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "pattern": {
                "resourceType": "UNKNOWN",
                "name": "string",
                "patternType": "UNKNOWN"
            },
            "entry": {
                "principal": "string",
                "host": "string",
                "operation": "UNKNOWN",
                "permissionType": "UNKNOWN"
            }
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /acls:search

Lists Kafka ACLs according to the supplied filter. Callable by Admins+AclUsers.

Example request:

POST /acls:search HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusters": {
            "kafka-cluster": "string"
        }
    },
    "aclBindingFilter": {
        "patternFilter": {
            "resourceType": "UNKNOWN",
            "name": "string",
            "patternType": "UNKNOWN"
        },
        "entryFilter": {
            "principal": "string",
            "host": "string",
            "operation": "UNKNOWN",
            "permissionType": "UNKNOWN"
        }
    }
}
Status Codes:
  • 200 OK

    Returns all AclBindings that match the given AclBindingFilter.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "pattern": {
                "resourceType": "UNKNOWN",
                "name": "string",
                "patternType": "UNKNOWN"
            },
            "entry": {
                "principal": "string",
                "host": "string",
                "operation": "UNKNOWN",
                "permissionType": "UNKNOWN"
            }
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

8.1 - Private RBAC UI - Cluster Visibility

POST /lookup/principals/{principal}/visibility

Endpoint for Confluent Control Center to determine visibilty of Kafka and its sub-clusters for the specifed principal. The intent is that this endpoint is called with cluster IDs that actually exist. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.

Example request:

POST /lookup/principals/{principal}/visibility HTTP/1.1
Host: example.com
Content-Type: application/json

[
    {
        "kafka-cluster": "string",
        "connect-clusters": [
            "string"
        ],
        "schema-registry-clusters": [
            "string"
        ],
        "ksql-clusters": [
            "string"
        ]
    }
]
Status Codes:
  • 200 OK

    Returns cluster IDs and true/false if the user has any role associated with it.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "kafka-cluster": {
            "id": "string",
            "visible": true
        },
        "connect-clusters": [
            {
                "id": "string",
                "visible": true
            }
        ],
        "schema-registry-clusters": [
            {
                "id": "string",
                "visible": true
            }
        ],
        "ksql-clusters": [
            {
                "id": "string",
                "visible": true
            }
        ]
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
GET /lookup/managed/clusters/principal/{principal}

Identifies the scopes for the rolebindings that a user can see. May include rolebindings from scopes and clusters that never existed or previously existed (in other words, rolebindings that have been decommissioned, but are still defined in the system). Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
Query Parameters:
 
  • clusterType (string) – Filter down by cluster type.
Status Codes:
  • 200 OK

    List of Scopes

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "clusters": {
                "kafka-cluster": "string",
                "connect-cluster": "string",
                "ksql-cluster": "string",
                "schema-registry-cluster": "string"
            }
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

8.2 - Private RBAC UI - My RoleBindings

GET /lookup/rolebindings/principal/{principal}

List all rolebindings for the specifed principal for all scopes and clusters that have any rolebindings. Be aware that this simply looks at the rolebinding data, and does not mean that the clusters actually exist. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
Query Parameters:
 
  • clusterType (string) – Filter down by a cluster type.
Status Codes:
  • 200 OK

    List of RoleBindings for the user per scope.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "scope": {
                "clusters": {
                    "kafka-cluster": "string",
                    "connect-cluster": "string",
                    "ksql-cluster": "string",
                    "schema-registry-cluster": "string"
                }
            },
            "rolebindings": {}
        }
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /lookup/rolebindings/principal/{principal}

List all rolebindings for the specifed principal and scope. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.

Example request:

POST /lookup/rolebindings/principal/{principal} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    Item per Scope

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "scope": {
            "clusters": {
                "kafka-cluster": "string",
                "connect-cluster": "string",
                "ksql-cluster": "string",
                "schema-registry-cluster": "string"
            }
        },
        "rolebindings": {}
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

8.3 - Private RBAC UI - Manage RoleBindings

POST /lookup/managed/clusters/principal/{principal}

Identify the rolebinding abilities (view vs manage) the user has on the specified scope. Used by the Confluent Control Center UI to control access to rolebinding add/remove buttons. Callable by Admins+ResourceOwners.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.

Example request:

POST /lookup/managed/clusters/principal/{principal} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    The rolebinding abilities the user has for a specified scope.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "cluster": [
            "string"
        ],
        "resources": {}
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    
POST /lookup/managed/rolebindings/principal/{principal}

Identify the rolebindings this user can see and manage. Callable by Admins+ResourceOwners.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
Query Parameters:
 
  • resourceType (string) – Filter down by resource type.

Example request:

POST /lookup/managed/rolebindings/principal/{principal} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    Rolebindings that the user can manage.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "scope": {
            "clusters": {
                "kafka-cluster": "string",
                "connect-cluster": "string",
                "ksql-cluster": "string",
                "schema-registry-cluster": "string"
            }
        },
        "cluster_role_bindings": {},
        "resource_role_bindings": {}
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

8.4 - Private RBAC UI - Creation Guidelines

POST /lookup/principal/{principal}/resource/{resourceType}/operation/{operation}

Summarizes what resources and rolebindings this principal is allowed to create. Callable by Admins+User.

Parameters:
  • principal (string) – Fully-qualified KafkaPrincipal string for a user or group.
  • resourceType (string) – The type of resource to create or the type of resource to specify when creating a new rolebinding.
  • operation (string) – “Create” for creating an actual resource, “AlterAccess” for creating a rolebinding for a user.

Example request:

POST /lookup/principal/{principal}/resource/{resourceType}/operation/{operation} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    A deduped and squashed view of the user’s rolebindings for creating resources or rolebindings.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "result": "SOME",
        "resourcePatterns": [
            {
                "resourceType": "Topic",
                "name": "billing-invoices",
                "patternType": "LITERAL"
            },
            {
                "resourceType": "Topic",
                "name": "investing-",
                "patternType": "PREFIXED"
            }
        ]
    }
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }
    

8.5 - Private RBAC UI - Cached User Store Information

POST /rbac/principals

List of users and groups, or just users, or just groups. For use by a rolebinding admin on the provided scope. Callable by Admins+ResourceOwners, but not broker super.users.

Query Parameters:
 
  • type (string) – The type of principals requested.

Example request:

POST /rbac/principals HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string"
    }
}
Status Codes:
  • 200 OK

    The list of principals for the requested type, or all principals.

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "Group:admin",
        "Group:developers",
        "Group:users",
        "User:alice",
        "User:bob",
        "User:charlie",
        "User:david"
    ]
    
  • default

    Error Response

    Example response:

    HTTP/1.1 default -
    Content-Type: application/json
    
    {
        "status_code": 1,
        "error_code": 1,
        "type": "string",
        "message": "string",
        "errors": [
            {
                "error_type": "string",
                "message": "string"
            }
        ]
    }