Confluent Metadata API Reference for Confluent Platform

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

ACL CRUD for legacy Kafka-managed and centralized MDS-based ACLs

Audit log configuration

Configuration governing which events get logged, and where those audit log events are sent. Works in conjunction with the Cluster Registry to push configuration changes to Kafka clusters.

Cluster registry

Tracking and naming CP components and clusters.

• Manually populated and updated by Admins.

• Leveraged by the Audit Log configuration.

• Leveraged by RBAC APIs to allow for RoleBinding calls to use “nice names” for clusters instead of cluster IDs.

Note

In all the RBAC CRUD APIs where you used to have to specify cluster IDs, if you have registered clusters with cluster registry, you can use the clusterName instead. However, you must adhere to the following restrictions:

• Use clusterName or clusters, but not both.

• When you use clusters, kafka-cluster is always required, because other clusters types do not have unique IDs.

Tenant management

Manages the lifecycle of logical Kafka clusters (LKCs) on a Confluent Private Cloud multi-tenant physical Kafka cluster (PKC). Lists, creates, and deactivates tenants, and manages each tenant’s quotas and limits. The API also exposes a reactivation endpoint, but reactivating a deactivated tenant always fails.

• Reading a tenant, or its quotas and limits, requires Describe on the Tenant resource type, granted at the PKC’s scope or at the tenant’s own scope.

• Creating a tenant requires Create on Tenant. Deactivating a tenant requires Delete. Reactivating a tenant, or updating its quotas and limits, requires Alter. MDS checks all three only at the PKC’s scope.

• The OrganizationAdmin and SystemAdmin roles, bound at the PKC’s scope, grant all of these operations. The TenantAdmin role, bound at a tenant’s own scope, can only read that tenant.

• To manage tenants, bind OrganizationAdmin at the PKC’s scope to the principal. A super.users principal has no special access to tenant management.

• Without a Confluent Private Cloud license, MDS allows at most three active tenants. Creating a fourth tenant fails with an HTTP 403 error. Apply a Confluent Private Cloud license to create more.

• A tenant’s LKC ID resolves to an ordinary kafka-cluster scope.

Caution

Don’t deactivate a tenant unless you intend to delete it. Within a few minutes, the brokers delete the tenant’s topics and their data, its ACLs, and its open transactions. A later reactivation request fails with an HTTP 410 error. If confluent.metadata.server.cpc.tenant.rolebinding.cleanup.enabled is true (the default), MDS also deletes the tenant’s role bindings on its next cleanup run.

MDS always returns null for a tenant’s bootstrapEndpoint field. To find a tenant’s bootstrap address, use its LogicalKafkaCluster custom resource instead. Clients outside the Kubernetes cluster use status.bootstrapEndpoint, which is set only when the Kafka cluster has external access configured. Clients inside the Kubernetes cluster use status.internalBootstrapEndpoint.

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 HTTP Basic authentication 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 HTTP Basic authentication 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).

• 409: Conflict. Adding a new resource or updating an existing resource that would result in a conflict with existing state.

  • This error can be thrown by Audit Logs and Cluster Registry APIs.

• 415: Invalid Content Type. Usually, a consequence of “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.

Explore the Metadata API

The Metadata Service ships with an OpenAPI spec that you can explore and interact with using an embedded Swagger UI.

To enable the embedded Swagger UI, specify the following property in the broker’s configuration when 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.

Note

Specify the same port that MDS is listening on as the Swagger UI port (the default is 8090).

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

Tokens and Authentication

GET /security/1.0/authenticate

Get a bearer token.

Callable by LDAP users.

Example request:

GET /security/1.0/authenticate HTTP/1.1
Host: example.com

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"
          }
      ]
  }
  

POST /security/1.0/impersonate

Impersonate a bearer token.

Callable by valid users.

Example request:

POST /security/1.0/impersonate HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "targetPrincipalType": "User",
    "targetPrincipalName": "bob"
}

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"
          }
      ]
  }
  

Authorization

PUT /security/1.0/authorize

Authorize operations against resourceType for a given user.

Callable by Admins+User.

Example request:

PUT /security/1.0/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 –

  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"
          }
      ]
  }
  

Metadata Service Operations

GET /security/1.0/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”.

Example request:

GET /security/1.0/activenodes/{protocol} HTTP/1.1
Host: example.com

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 /security/1.0/metadataClusterId

Returns the ID of the Kafka cluster that MDS is running on.

Callable by LDAP users.

Example request:

GET /security/1.0/metadataClusterId HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Lists other nodes running the Metadata Service.

  Example response:

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

GET /security/1.0/features

What features the running version of MDS supports.

This endpoint does not require authentication.

Example request:

GET /security/1.0/features HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  What features MDS supports, and a human friendly description of them.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "features": {},
      "legend": {}
  }
  

RBAC - Role Definitions

GET /security/1.0/roles

Returns all the roles defined in the system.

For information and developer purposes.

Callable by LDAP users.

Example request:

GET /security/1.0/roles HTTP/1.1
Host: example.com

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 /security/1.0/roles/{roleName}

List the resourceType and operations allowed for a given role.

Callable by LDAP users.

Parameters:

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

Example request:

GET /security/1.0/roles/{roleName} HTTP/1.1
Host: example.com

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 /security/1.0/roleNames

Returns the names of all the roles defined in the system.

For information and developer purposes.

Callable by LDAP users.

Example request:

GET /security/1.0/roleNames HTTP/1.1
Host: example.com

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"
          }
      ]
  }
  

RBAC - RoleBinding CRUD

POST /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName}/resources HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusterName": "string",
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string",
            "cmf": "string",
            "flink-environment": "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 /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusterName": "string",
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string",
            "cmf": "string",
            "flink-environment": "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 /security/1.0/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 /security/1.0/principals/{principal}/roles/{roleName}/bindings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "scope": {
        "clusterName": "string",
        "clusters": {
            "kafka-cluster": "string",
            "connect-cluster": "string",
            "ksql-cluster": "string",
            "schema-registry-cluster": "string",
            "cmf": "string",
            "flink-environment": "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"
          }
      ]
  }
  

RBAC - RoleBinding Summaries

POST /security/1.0/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 /security/1.0/lookup/principals/{principal}/roleNames HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/lookup/principal/{principal}/resources HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/lookup/role/{roleName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/lookup/role/{roleName}/resource/{resourceType}/name/{resourceName} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "clusterName": "string",
    "clusters": {
        "kafka-cluster": "string",
        "connect-cluster": "string",
        "ksql-cluster": "string",
        "schema-registry-cluster": "string",
        "cmf": "string",
        "flink-environment": "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"
          }
      ]
  }
  

Kafka ACL Management

POST /security/1.0/acls

Creates Kafka ACLs for given AclBinding.

Callable by Admins+AclUsers.

Example request:

POST /security/1.0/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 /security/1.0/acls

Deletes Kafka ACLs according to the supplied filter.

Callable by Admins+AclUsers.

Example request:

DELETE /security/1.0/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 /security/1.0/acls:search

Lists Kafka ACLs according to the supplied filter.

Callable by Admins+AclUsers.

search_all_acls - Search for all ACLs:

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

{
    "scope": {
        "clusters": {
            "kafka-cluster": "kafka-cluster-id"
        }
    },
    "aclBindingFilter": {
        "patternFilter": {
            "resourceType": "ANY",
            "patternType": "ANY"
        },
        "entryFilter": {
            "operation": "ANY",
            "permissionType": "ANY"
        }
    }
}

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"
          }
      ]
  }
  

Cluster Registry

GET /security/1.0/registry/clusters

Returns a list of all clusters in the registry, optionally filtered by cluster type and/or backing Kafka cluster.

If the calling principal doesn’t have permissions to see the full cluster info, some information (“hosts”, “protocol”, etc) is redacted.

Kafka listener entries (scope {kafka-cluster, kafka-listener}) are only returned when clusterType=kafka-listener is specified. They are visible to callers with access to the parent {kafka-cluster} scope.

Callable by Admins+User.

Query Parameters:

• clusterType (string) – Optionally filter down by cluster type. Use kafka-listener to list the client-facing listeners registered for Kafka clusters.

• kafkaCluster (string) – Optionally filter down to entries backed by the given Kafka cluster id, i.e. whose scope.clusters.kafka-cluster equals it. ANDed with clusterType.

Example request:

GET /security/1.0/registry/clusters HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  List of Clusters.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  [
      {
          "clusterName": "string",
          "scope": {
              "clusters": {
                  "kafka-cluster": "string",
                  "connect-cluster": "string",
                  "ksql-cluster": "string",
                  "schema-registry-cluster": "string",
                  "cmf": "string",
                  "flink-environment": "string",
                  "kafka-listener": "string"
              }
          },
          "hosts": [
              {
                  "host": "string",
                  "port": 1
              }
          ],
          "protocol": "SASL_PLAINTEXT"
      }
  ]
  

• 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 /security/1.0/registry/clusters

Define/overwrite named clusters.

May result in a 409 Conflict if the name and scope combination of any cluster conflicts with existing clusters in the registry.

A client-facing Kafka listener is registered as its own entry with scope {kafka-cluster: <id>, kafka-listener: <name>} and protocol PLAINTEXT, SSL, SASL_PLAINTEXT or SASL_SSL. Writing a listener entry requires the same permissions as writing its parent {kafka-cluster: <id>} entry; the parent entry need not exist. Listener entries cannot be used as role binding scopes.

Callable by Admins.

Example request:

POST /security/1.0/registry/clusters HTTP/1.1
Host: example.com
Content-Type: application/json

[
    {
        "clusterName": "string",
        "scope": {
            "clusters": {
                "kafka-cluster": "string",
                "connect-cluster": "string",
                "ksql-cluster": "string",
                "schema-registry-cluster": "string",
                "cmf": "string",
                "flink-environment": "string",
                "kafka-listener": "string"
            }
        },
        "hosts": [
            {
                "host": "string",
                "port": 1
            }
        ],
        "protocol": "SASL_PLAINTEXT"
    }
]

Status Codes:

• 204 No Content – Clusters added.

• 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 /security/1.0/registry/clusters/{clusterName}

Returns the information for a single named cluster, assuming the cluster exists and is visible to the calling principal.

Callable by Admins+User.

Parameters:

• clusterName (string) – The name of cluster (ASCII printable characters without spaces).

Example request:

GET /security/1.0/registry/clusters/{clusterName} HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  The named cluster, if it exists and the caller has permission to see it.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "clusterName": "string",
      "scope": {
          "clusters": {
              "kafka-cluster": "string",
              "connect-cluster": "string",
              "ksql-cluster": "string",
              "schema-registry-cluster": "string",
              "cmf": "string",
              "flink-environment": "string",
              "kafka-listener": "string"
          }
      },
      "hosts": [
          {
              "host": "string",
              "port": 1
          }
      ],
      "protocol": "SASL_PLAINTEXT"
  }
  

• 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 /security/1.0/registry/clusters/{clusterName}

Remove a named cluster from the registry.

Callable by Admins.

Parameters:

• clusterName (string) – The name of cluster (ASCII printable characters without spaces).

Status Codes:

• 204 No Content – Cluster 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"
          }
      ]
  }
  

Multi-Tenancy - Tenants

GET /security/1.0/tenants

List tenants visible to the calling principal.

OrgAdmins see all tenants. Other callers see only tenants they hold a TenantAdmin (or equivalent) binding on; the rest are filtered out server-side.

Use the optional kafka-cluster-id query parameter to restrict results to a single physical Kafka cluster (PKC). v1 each MDS serves exactly one PKC, so a non-matching filter short-circuits to an empty list. When MDS is extended to serve multiple PKCs, omitting the filter will fan out across them.

Use the optional phase query parameter to filter by lifecycle phase. When omitted, the result includes both Running tenants and Deactivated tenants that are still within their reactivation window. Tenants whose reactivation window has elapsed (effectively deleted) are never returned, regardless of phase.

Callable by Admins+User.

Query Parameters:

• kafka-cluster-id (string) – Optional PKC filter. When omitted, returns every tenant visible to the caller on this MDS.

• phase (string) – Optional lifecycle-phase filter (case-insensitive). running returns only active tenants; deactivated returns only tenants within their reactivation window. When omitted, both are returned. Tenants past their reactivation window are never returned.

Example request:

GET /security/1.0/tenants HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  List of tenants visible to the caller.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  [
      {
          "id": "string",
          "name": "string",
          "phase": "Running",
          "bootstrapEndpoint": "string",
          "creationDate": "2026-10-27T13:59:22.368587",
          "deletionDate": "2026-10-27T13:59:22.368587"
      }
  ]
  

• 400 Bad Request –

  Invalid phase query parameter (must be running or deactivated).

  Example response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

POST /security/1.0/tenants

Create a new tenant. MDS assigns the lkc-id.

Body is a CreateTenantRequest; the body’s kafka_cluster_id selects the PKC. v1 the value must match the local MDS’s Kafka cluster id (mismatch → 400 Bad Request). The server-assigned id is included in the response and in the Location header.

The tenant name must be unique among running tenants and deactivated tenants still within their reactivation window; a duplicate name returns 409 Conflict. A name frees up for reuse only after a deactivated tenant’s reactivation window has elapsed.

Callable by Admins.

Example request:

POST /security/1.0/tenants HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "kafka_cluster_id": "string",
    "name": "string",
    "quotas": {
        "network_ingress_byte_rate": 1,
        "network_egress_byte_rate": 1,
        "broker_request_threads": 1.0
    },
    "limits": {
        "max_partitions": 1,
        "max_message_size_bytes": 1
    }
}

Status Codes:

• 201 Created –

  Tenant created. The Location header carries the tenant URL.

  Example response:

  HTTP/1.1 201 Created
  Content-Type: application/json
  
  {
      "id": "string",
      "name": "string",
      "phase": "Running",
      "bootstrapEndpoint": "string",
      "creationDate": "2026-10-27T13:59:22.368587",
      "deletionDate": "2026-10-27T13:59:22.368587"
  }
  

• 400 Bad Request –

  Invalid request — e.g. the body’s kafka_cluster_id does not match this MDS’s Kafka cluster id, or a quota/limit value is invalid.

  Example response:

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

• 403 Forbidden –

  Either the caller is not authorized to create tenants, or no CPC-entitled license is present and this PKC has already reached the free-tier limit of 3 tenants.

  Example response:

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

• 409 Conflict –

  A tenant with the same name already exists. Tenant names must be unique among tenants that are running or deactivated but still within their reactivation window. A name becomes available for reuse only once a deactivated tenant’s reactivation window has elapsed.

  Example response:

  HTTP/1.1 409 Conflict
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

Response Headers:

• Location – Path of the created tenant resource.

GET /security/1.0/tenants/quotas-and-limits

Bulk-read quotas and limits for every tenant visible to the calling principal.

Returns quotas and limits for every tenant visible to the calling principal, in a single call.

Use the optional kafka-cluster-id query parameter to restrict results to a single physical Kafka cluster (PKC), same semantics as GET /tenants.

Callable by Admins+User.

Query Parameters:

• kafka-cluster-id (string) – Optional PKC filter. When omitted, returns every tenant visible to the caller on this MDS.

• phase (string) – Optional lifecycle-phase filter (case-insensitive). running returns only active tenants; deactivated returns only tenants within their reactivation window. When omitted, both are returned. Tenants past their reactivation window are never returned.

Example request:

GET /security/1.0/tenants/quotas-and-limits HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Quotas and limits for every tenant visible to the caller.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  [
      {
          "tenantId": "string",
          "quotas": {
              "network_ingress_byte_rate": 1,
              "network_egress_byte_rate": 1,
              "broker_request_threads": 1.0
          },
          "limits": {
              "max_partitions": 1,
              "max_message_size_bytes": 1
          }
      }
  ]
  

• 400 Bad Request –

  Invalid phase query parameter (must be running or deactivated).

  Example response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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 /security/1.0/tenants/{tenantId}

Get a single tenant by id.

Returns 404 if the tenant does not exist or the caller has no visibility on it.

Callable by Admins+User.

Parameters:

• tenantId (string)

Example request:

GET /security/1.0/tenants/{tenantId} HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  The requested tenant.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "id": "string",
      "name": "string",
      "phase": "Running",
      "bootstrapEndpoint": "string",
      "creationDate": "2026-10-27T13:59:22.368587",
      "deletionDate": "2026-10-27T13:59:22.368587"
  }
  

• 404 Not Found –

  Tenant does not exist, or the caller has no visibility on it.

  Example response:

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

DELETE /security/1.0/tenants/{tenantId}

Soft-delete (deactivate) a tenant.

Writes a deletionDate 7 days in the future to the tenant metadata topic and returns 202. The tenant’s phase flips to Deactivated immediately and brokers deny new connections from that moment. The window between now and deletionDate is the reactivation window: a subsequent POST /tenants/{tenantId}/reactivate clears the scheduled deactivation. Once deletionDate arrives, the broker’s TenantLifecycleManager cleans up topics, ACLs, and in-flight transactions; past that point reactivation returns 410 Gone. The tenant record itself is preserved permanently so the lkc-id is never reused.

Idempotent: calling DELETE on a tenant that is already Deactivated returns 202 but does not write a new record — the original deletionDate is preserved, so callers cannot extend the cleanup window by repeating the call.

Callable by Admins.

Parameters:

• tenantId (string)

Status Codes:

• 202 Accepted – Deactivation accepted. Cleanup happens asynchronously.

• 403 Forbidden –

  Caller is not authorized to deactivate this tenant.

  Example response:

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

• 404 Not Found –

  Tenant does not exist.

  Example response:

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

POST /security/1.0/tenants/{tenantId}/reactivate

Reactivate a deactivated tenant within its reactivation window.

Clears the tenant’s deletionDate, flipping phase back to Running. Allowed only while the tenant is Deactivated and the scheduled deletionDate is still in the future (the reactivation window). Past deletionDate the broker has cleaned up the tenant and reactivation returns 410 Gone.

Idempotent: calling reactivate on a tenant that is already Running returns 200 with the current tenant state and produces no new record.

Callable by Admins.

Parameters:

• tenantId (string)

Status Codes:

• 200 OK –

  Tenant is Running. Body is the current tenant state.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "id": "string",
      "name": "string",
      "phase": "Running",
      "bootstrapEndpoint": "string",
      "creationDate": "2026-10-27T13:59:22.368587",
      "deletionDate": "2026-10-27T13:59:22.368587"
  }
  

• 403 Forbidden –

  Caller is not authorized to reactivate this tenant.

  Example response:

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

• 404 Not Found –

  Tenant does not exist.

  Example response:

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

• 410 Gone –

  Reactivation window has elapsed; the tenant has been (or will be) cleaned up.

  Example response:

  HTTP/1.1 410 Gone
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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 /security/1.0/tenants/{tenantId}/quotas-and-limits

Get the quotas and limits for a tenant.

Callable by Admins+User.

Parameters:

• tenantId (string)

Example request:

GET /security/1.0/tenants/{tenantId}/quotas-and-limits HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  The tenant’s current quotas and limits.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "quotas": {
          "network_ingress_byte_rate": 1,
          "network_egress_byte_rate": 1,
          "broker_request_threads": 1.0
      },
      "limits": {
          "max_partitions": 1,
          "max_message_size_bytes": 1
      }
  }
  

• 404 Not Found –

  Tenant does not exist, or the caller has no visibility on it.

  Example response:

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

PUT /security/1.0/tenants/{tenantId}/quotas-and-limits

Replace the entire quotas/limits object.

Full replace — any field omitted from the body is cleared (treated as “unlimited”, except broker_request_threads, which falls back to the broker default).

Callable by Admins.

Parameters:

• tenantId (string)

Example request:

PUT /security/1.0/tenants/{tenantId}/quotas-and-limits HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "quotas": {
        "network_ingress_byte_rate": 1,
        "network_egress_byte_rate": 1,
        "broker_request_threads": 1.0
    },
    "limits": {
        "max_partitions": 1,
        "max_message_size_bytes": 1
    }
}

Status Codes:

• 200 OK –

  Replaced. Body is the new state.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "quotas": {
          "network_ingress_byte_rate": 1,
          "network_egress_byte_rate": 1,
          "broker_request_threads": 1.0
      },
      "limits": {
          "max_partitions": 1,
          "max_message_size_bytes": 1
      }
  }
  

• 400 Bad Request –

  Invalid quota/limit values in the request body.

  Example response:

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

• 403 Forbidden –

  Caller is not authorized to modify this tenant’s quotas and limits.

  Example response:

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

• 404 Not Found –

  Tenant does not exist.

  Example response:

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

PATCH /security/1.0/tenants/{tenantId}/quotas-and-limits

Apply an RFC 7396 merge-patch on quotas/limits.

Merge-patch semantics: - Keys present with a value: that field is set to the value. - Keys present with null: that field is cleared (becomes “unlimited”, except broker_request_threads, which falls back to the broker default). - Keys absent: the field is unchanged.

Content-Type must be application/merge-patch+json. Callable by Admins.

Parameters:

• tenantId (string)

Status Codes:

• 200 OK –

  Patched. Body is the new merged state.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "quotas": {
          "network_ingress_byte_rate": 1,
          "network_egress_byte_rate": 1,
          "broker_request_threads": 1.0
      },
      "limits": {
          "max_partitions": 1,
          "max_message_size_bytes": 1
      }
  }
  

• 400 Bad Request –

  Invalid quota/limit values in the request body.

  Example response:

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

• 403 Forbidden –

  Caller is not authorized to modify this tenant’s quotas and limits.

  Example response:

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

• 404 Not Found –

  Tenant does not exist.

  Example response:

  HTTP/1.1 404 Not Found
  Content-Type: application/json
  
  {
      "status_code": 1,
      "error_code": 1,
      "type": "string",
      "message": "string",
      "errors": [
          {
              "error_type": "string",
              "message": "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"
          }
      ]
  }
  

Audit Log Configuration

GET /security/1.0/audit/config

Get the entire audit log configuration, including the live retention time policy values (``retention_ms``) for the destination topics.

Requires the “AuditAdmin” role on the metadata service (MDS) cluster and every Kafka cluster in the cluster registry.

Callable by Admins.

Example request:

GET /security/1.0/audit/config HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  The entire audit log configuration.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "destinations": {
          "topics": {
              "confluent-audit-log-events_general_allowed_events": {
                  "retention_ms": 2592000000
              },
              "confluent-audit-log-events_general_denied_events": {
                  "retention_ms": 7776000000
              },
              "confluent-audit-log-events_finance_reads": {
                  "retention_ms": 157680000000
              }
          }
      },
      "excluded_principals": [
          "User:Alice",
          "User:service_account_id"
      ],
      "default_topics": {
          "allowed": "confluent-audit-log-events_general_allowed_events",
          "denied": "confluent-audit-log-events_general_denied_events"
      },
      "routes": {
          "crn://mds1.example.com/kafka=*/topic=*": {
              "management": {
                  "allowed": "",
                  "denied": ""
              },
              "authorize": {
                  "allowed": "confluent-audit-log-events_general_allowed_events",
                  "denied": "confluent-audit-log-events_general_denied_events"
              }
          },
          "crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/topic=finance-*": {
              "consume": {
                  "allowed": "confluent-audit-log-events_finance_reads",
                  "denied": "confluent-audit-log-events_general_denied_events"
              },
              "interbroker": {
                  "allowed": "",
                  "denied": ""
              }
          }
      },
      "metadata": {
          "resource_version": "ASNFZ4mrze8BI0VniavN7w",
          "updated_at": "2019-09-09T12:34:56Z"
      }
  }
  

PUT /security/1.0/audit/config

Update the entire audit log configuration on the MDS cluster and all Kafka clusters known to the cluster registry.

Also creates missing destination topics on the destination cluster and updates the retention time policy of destination topics, if necessary.

Requires the “AuditAdmin” role on the MDS cluster and every Kafka cluster in the cluster registry.

May result in a 409 conflict error status if the resource_version in the JSON body of the request does not match the current version.

Callable by Admins.

Example request:

PUT /security/1.0/audit/config HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "destinations": {
        "topics": {
            "confluent-audit-log-events_general_allowed_events": {
                "retention_ms": 2592000000
            },
            "confluent-audit-log-events_general_denied_events": {
                "retention_ms": 7776000000
            },
            "confluent-audit-log-events_finance_reads": {
                "retention_ms": 157680000000
            }
        }
    },
    "excluded_principals": [
        "User:Alice",
        "User:service_account_id"
    ],
    "default_topics": {
        "allowed": "confluent-audit-log-events_general_allowed_events",
        "denied": "confluent-audit-log-events_general_denied_events"
    },
    "routes": {
        "crn://mds1.example.com/kafka=*/topic=*": {
            "management": {
                "allowed": "",
                "denied": ""
            },
            "authorize": {
                "allowed": "confluent-audit-log-events_general_allowed_events",
                "denied": "confluent-audit-log-events_general_denied_events"
            }
        },
        "crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/topic=finance-*": {
            "consume": {
                "allowed": "confluent-audit-log-events_finance_reads",
                "denied": "confluent-audit-log-events_general_denied_events"
            },
            "interbroker": {
                "allowed": "",
                "denied": ""
            }
        }
    },
    "metadata": {
        "resource_version": "ASNFZ4mrze8BI0VniavN7w",
        "updated_at": "2019-09-09T12:34:56Z"
    }
}

Status Codes:

• 200 OK –

  The current audit log configuration spec

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "destinations": {
          "bootstrap_servers": [
              "string"
          ],
          "topics": {}
      },
      "excluded_principals": [
          "string"
      ],
      "default_topics": {
          "allowed": "string",
          "denied": "string"
      },
      "routes": {},
      "metadata": {
          "resource_version": "string",
          "updated_at": "2026-10-27T13:59:22.368587",
          "modified_since": "2026-10-27T13:59:22.368587"
      }
  }
  

• 409 Conflict –

  Concurrent modification resulted in a conflict. Response will be the current audit log configuration.

  Example response:

  HTTP/1.1 409 Conflict
  Content-Type: application/json
  
  {
      "destinations": {
          "bootstrap_servers": [
              "string"
          ],
          "topics": {}
      },
      "excluded_principals": [
          "string"
      ],
      "default_topics": {
          "allowed": "string",
          "denied": "string"
      },
      "routes": {},
      "metadata": {
          "resource_version": "string",
          "updated_at": "2026-10-27T13:59:22.368587",
          "modified_since": "2026-10-27T13:59:22.368587"
      }
  }
  

GET /security/1.0/audit/routes

Lists all currently defined routes that match the queried resource or its sub-resources.

Multiple routes may match a resource, but only the most specific route will be selected for events related to the resource. This endpoint returns all matching routes regardless of whether or not they would actually be selected, or ignored in favor of a more specific route.

Requires the “AuditAdmin” role on the metadata service (MDS) cluster and every Kafka cluster in the cluster registry.

Callable by Admins.

The CRN patterns in the audit log config routes can contain wildcards. So a route with a CRN pattern like crn://mds.example.com/kafka=*/topic=finance-* would match events associated with the topic at address crn://mds.example.com/kafka=abc123/topic=finance-deposits, or events associated with the topic at crn://mds.example.com/kafka=xyz789/topic=finance-chargebacks, but would not match events associated with the topic crn://mds.example.com/kafka=abc123/topic=server-deployments. So a route’s CRN pattern can match events from more than one resource, based on where the pattern’s wildcards are.

It is possible to write multiple routes with different CRN patterns that match a given resource’s CRN. For example: the resource at crn://mds.example.com/kafka=abc123/topic=finance-chargebacks is matched by any of the following route CRN patterns:

• crn://mds.example.com/kafka=*/topic=*

• crn://mds.example.com/kafka=abc123/topic=*

• crn://mds.example.com/kafka=*/topic=finance-*

When there are multiple matching routes for an event, we select the matching route with the most specific CRN pattern. The most specific CRN pattern is the one with the greatest length before its first wildcard. So in the above example, crn://mds.example.com/kafka=abc123/topic=* wins.

To break a tie, ignore the prefix that the patterns have in common. So, for example crn://mds.example.com/kafka=*/topic=finance-* is more specific than crn://mds.example.com/kafka=*/topic=*.

This endpoint lists all currently defined routes that match the queried resource or its sub-resources, regardless of whether or not they would actually be selected, or ignored in favor of a more specific route.

A query pattern like …

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=qa-test

… would match all of the following routes …

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=qa-test/connector=from-db4

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=qa-test/connector=*

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=*/connector=*

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=qa-*

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=*

crn://mds1.example.com/kafka=*/connect=qa-*

crn://mds1.example.com/kafka=*/connect=qa-*/connector=*

… but would not match any of these routes …

crn://mds1.example.com/kafka=*/ksql=*

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=stg-*

crn://mds1.example.com/kafka=zyxwv-UTSRQPO_98765432/connect=qa-*

crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/topic=qa-*

Query Parameters:

• q (string) – A Confluent resource name (CRN) .

Example request:

GET /security/1.0/audit/routes HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Matching routes and their rules

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "default_topics": {
          "allowed": "confluent-audit-log-events_general_allowed_events",
          "denied": "confluent-audit-log-events_general_denied_events"
      },
      "routes": {
          "crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=qa-test/connector=from-db4": {
              "management": {
                  "allowed": "",
                  "denied": ""
              }
          },
          "crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/connect=*": {
              "authorize": {
                  "allowed": "confluent-audit-log-events_abc-connector-allowed",
                  "denied": "confluent-audit-log-events_abc-connector-denied"
              }
          }
      }
  }
  

GET /security/1.0/audit/lookup

Returns the route describing how messages regarding this CRN would be routed.

Requires the “AuditAdmin” role on the metadata service (MDS) cluster and every Kafka cluster in the cluster registry.

The CRN patterns in the audit log config routes can contain wildcards. So a route with a CRN pattern like crn://mds.example.com/kafka=*/topic=finance-* would match events associated with the topic at address crn://mds.example.com/kafka=abc123/topic=finance-deposits, or events associated with the topic at crn://mds.example.com/kafka=xyz789/topic=finance-chargebacks, but would not match events associated with the topic crn://mds.example.com/kafka=abc123/topic=server-deployments. So a route’s CRN pattern can match events from more than one resource, based on where the pattern’s wildcards are.

It is possible to write multiple routes with different CRN patterns that match a given resource’s CRN. For example: the resource at crn://mds.example.com/kafka=abc123/topic=finance-chargebacks is matched by any of the following route CRN patterns:

• crn://mds.example.com/kafka=*/topic=*

• crn://mds.example.com/kafka=abc123/topic=*

• crn://mds.example.com/kafka=*/topic=finance-*

When there are multiple matching routes for an event, we select the matching route with the most specific CRN pattern. The most specific CRN pattern is the one with the greatest length before its first wildcard. So in the above example, crn://mds.example.com/kafka=abc123/topic=* wins.

To break a tie, ignore the prefix that the patterns have in common. So, for example crn://mds.example.com/kafka=*/topic=finance-* is more specific than crn://mds.example.com/kafka=*/topic=*.

This endpoint resolves the matching and precedence rules of all configured audit log routes for you, and returns the one selected (most specific) matching route describing how messages regarding the given CRN would be routed. Callable by Admins.

Query Parameters:

• crn (string) – A Confluent resource name (CRN).

Example request:

GET /security/1.0/audit/lookup HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  The CRN pattern of the route that will be selected and used by the system (or else the string "default"), and the route’s rules for various audit log event categories. Categories include produce, consume, interbroker, authorize, authentication, management, heartbeat`, and describe. If needed, the server fills in any missing or null values in the rules by coalescing with defaults: authentication, authorize, and management categories will default to the destination topics specified in default_topics. All other categories default to an empty string. Rules that resolve to an empty string indicate that events will be discarded.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "route": "crn://mds1.example.com/kafka=abcde_FGHIJKL-01234567/topic=finance-*",
      "categories": {
          "authorize": {
              "allowed": "confluent-audit-log-events_general_allowed_events",
              "denied": "confluent-audit-log-events_general_denied_events"
          },
          "consume": {
              "allowed": "",
              "denied": "confluent-audit-log-events_finance_denied"
          },
          "describe": {
              "allowed": "",
              "denied": ""
          },
          "heartbeat": {
              "allowed": "",
              "denied": ""
          },
          "interbroker": {
              "allowed": "",
              "denied": ""
          },
          "management": {
              "allowed": "confluent-audit-log-events_general_allowed_events",
              "denied": "confluent-audit-log-events_general_denied_events"
          },
          "produce": {
              "allowed": "confluent-audit-log-events_finance_produce_allowed",
              "denied": "confluent-audit-log-events_finance_denied"
          }
      }
  }
  

Private RBAC UI - Cluster Visibility

POST /security/1.0/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 /security/1.0/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,
          "clusterName": "string"
      },
      "connect-clusters": [
          {
              "id": "string",
              "visible": true,
              "clusterName": "string"
          }
      ],
      "schema-registry-clusters": [
          {
              "id": "string",
              "visible": true,
              "clusterName": "string"
          }
      ],
      "ksql-clusters": [
          {
              "id": "string",
              "visible": true,
              "clusterName": "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 /security/1.0/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.

Example request:

GET /security/1.0/lookup/managed/clusters/principal/{principal} HTTP/1.1
Host: example.com

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",
              "cmf": "string",
              "flink-environment": "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"
          }
      ]
  }
  

Private RBAC UI - My RoleBindings

GET /security/1.0/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.

Example request:

GET /security/1.0/lookup/rolebindings/principal/{principal} HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  List of RoleBindings for the user per scope.

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  [
      {
          "scope": {
              "clusterName": "string",
              "clusters": {
                  "kafka-cluster": "string",
                  "connect-cluster": "string",
                  "ksql-cluster": "string",
                  "schema-registry-cluster": "string",
                  "cmf": "string",
                  "flink-environment": "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 /security/1.0/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 /security/1.0/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",
        "cmf": "string",
        "flink-environment": "string"
    }
}

Status Codes:

• 200 OK –

  Item per Scope

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "scope": {
          "clusterName": "string",
          "clusters": {
              "kafka-cluster": "string",
              "connect-cluster": "string",
              "ksql-cluster": "string",
              "schema-registry-cluster": "string",
              "cmf": "string",
              "flink-environment": "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"
          }
      ]
  }
  

Private RBAC UI - Manage RoleBindings

POST /security/1.0/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 /security/1.0/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",
        "cmf": "string",
        "flink-environment": "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 /security/1.0/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 /security/1.0/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",
        "cmf": "string",
        "flink-environment": "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",
              "cmf": "string",
              "flink-environment": "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"
          }
      ]
  }
  

Private RBAC UI - Creation Guidelines

POST /security/1.0/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 /security/1.0/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",
        "cmf": "string",
        "flink-environment": "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"
          }
      ]
  }
  

Private RBAC UI - Cached User Store Information

POST /security/1.0/rbac/principals

List of MDS cached users and 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 /security/1.0/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",
        "cmf": "string",
        "flink-environment": "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"
          }
      ]
  }
  

SSO - Device Authorization

POST /security/1.0/oidc/device/authenticate

Provides user authentication details and device polling for authentication status

This initiates user authentication in CLI.

Response contains 1. user_code and verification_uri which are used by user to authenticate from the identity provider (IdP). 2. key is used to poll the IdP to check if the user has authorized and logged in. 3. interval to hint client about polling frequency.

Status Codes:

• 200 OK –

  Successful authentication initiation

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "user_code": "string",
      "verification_uri": "string",
      "key": "string",
      "interval": 1,
      "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"
          }
      ]
  }
  

POST /security/1.0/oidc/device/check-auth

Provides information about current status of user authentication

Checks if the user has authorized and logged in. If the user has authorized, then the response contains the auth token, and the complete flag is set to true.

If the user has not authorized in right time or some other error occurred, then the response contains the error details, and again complete flag is set to true.

Otherwise, in case of pending auth, the response contains the status, description and the complete flag is set to false.

Example request:

POST /security/1.0/oidc/device/check-auth HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "user_code": "string",
    "key": "string"
}

Status Codes:

• 200 OK –

  Successful response

  authorization_pending:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "user_code": "CRMCWZLK",
      "complete": false,
      "status": "authorization_pending",
      "description": "The device authorization is pending. Please try again later."
  }
  

  slow_down:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "user_code": "CRMCWZLK",
      "complete": false,
      "status": "slow_down",
      "description": "Slow down the polling frequency. Please try again later."
  }
  

  expired_token:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "user_code": "CRMCWZLK",
      "complete": false,
      "status": "expired_token",
      "description": "The device code has expired. You have already requested token."
  }
  

  authentication_success:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "user_code": "CRMCWZLK",
      "complete": true,
      "status": "success",
      "description": "Authentication successful.",
      "auth_token": "json web token",
      "expires_in": 900
  }
  

• 403 Forbidden –

  Forbidden

  invalid_key:

  HTTP/1.1 403 Forbidden
  Content-Type: application/json
  
  {
      "status_code": 403,
      "message": "Invalid key!"
  }
  

• 500 Internal Server Error –

  Some error happened when autheticating

  wrong_token_endpoint:

  HTTP/1.1 500 Internal Server Error
  Content-Type: application/json
  
  {
      "status_code": 500,
      "message": "Server Error"
  }
  

• 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 /security/1.0/oidc/device/extend-auth

Extend auth by generating a new token

Attempts to refresh the Confluent token if applicable, based on the provided JwtPrincipal.

If refresh token is configured to be used, the session is extended until expiry time of new ID token requested using the refresh token.

Else session is extended until min(mex, currentTime`+ `sessionTokenExpiryConfig) where mex is the claim already present in auth token.

Example request:

POST /security/1.0/oidc/device/extend-auth HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "access_token": "string",
    "refresh_token": "string"
}

Status Codes:

• 200 OK –

  Get a token with extended expiry.

  success:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "auth_token": "json web token",
      "expires_in": 900
  }
  

• 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"
          }
      ]
  }
  

Sanitize token

POST /security/1.0/token/sanitize

Sanitize token to remove claims

Callable by valid user.

Example request:

POST /security/1.0/token/sanitize HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "accessToken": "<A Valid JWT token>",
    "sanitizeClaims": [
        "mex"
    ]
}

Status Codes:

• 200 OK –

  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"
          }
      ]
  }
  

Related content

• How to enable DEBUG Logging for Metadata Service (MDS) or RBAC (Confluent Support)