Declaratively manage Self-Service resources - Application, ApplicationInstance, and TopicPolicy - so platform teams can enforce naming and configuration standards while application teams own their topic lifecycle as code.
openapi: 3.0.1
info:
title: Conduktor API
description: >-
Unified specification of the Conduktor REST API surface, covering the Conduktor
Console API (clusters, certificates, users, groups, RBAC permissions, and
declarative Self-Service resources) and the Conduktor Gateway API
(interceptors, virtual clusters, service accounts, and tokens). Console
endpoints authenticate with an admin-generated Bearer API key; Gateway admin
endpoints authenticate with Basic auth. Host names are deployment-specific.
termsOfService: https://www.conduktor.io/terms-and-conditions/
contact:
name: Conduktor Support
url: https://www.conduktor.io/contact/
version: '1.0'
servers:
- url: https://{consoleHost}
description: Conduktor Console deployment host
variables:
consoleHost:
default: localhost:8080
description: Host and port of your Conduktor Console deployment
- url: https://{gatewayAdminHost}:8888
description: Conduktor Gateway admin API host
variables:
gatewayAdminHost:
default: localhost
description: Host of your Conduktor Gateway admin endpoint
tags:
- name: Clusters
description: Manage Kafka cluster registrations in Console
- name: Certificates
description: Manage cluster certificates in Console
- name: Users
description: Manage organization users in Console
- name: Groups
description: Manage groups and RBAC permissions in Console
- name: Self-Service
description: Declarative Application, ApplicationInstance, and TopicPolicy resources
- name: Interceptors
description: Gateway interceptors for data security, quality, and governance
- name: Virtual Clusters
description: Gateway virtual clusters, service accounts, and tokens
paths:
/public/v1/configs/{cluster}/clusters:
get:
operationId: listClusters
tags:
- Clusters
summary: List configured Kafka clusters
security:
- bearerAuth: []
responses:
'200':
description: A list of cluster configurations.
content:
application/yaml:
schema:
type: array
items:
$ref: '#/components/schemas/KafkaCluster'
/public/v1/clusters:
get:
operationId: getClusters
tags:
- Clusters
summary: List registered Kafka clusters
security:
- bearerAuth: []
responses:
'200':
description: Registered clusters.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/KafkaCluster'
post:
operationId: upsertCluster
tags:
- Clusters
summary: Create or update a Kafka cluster registration
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KafkaCluster'
responses:
'200':
description: Cluster created or updated.
content:
application/json:
schema:
$ref: '#/components/schemas/KafkaCluster'
/public/v1/clusters/{cluster}:
delete:
operationId: deleteCluster
tags:
- Clusters
summary: Delete a Kafka cluster registration
security:
- bearerAuth: []
parameters:
- name: cluster
in: path
required: true
schema:
type: string
responses:
'204':
description: Cluster deleted.
/public/v1/certificates:
get:
operationId: listCertificates
tags:
- Certificates
summary: List trusted certificates
security:
- bearerAuth: []
responses:
'200':
description: Certificates.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Certificate'
post:
operationId: upsertCertificate
tags:
- Certificates
summary: Create or update a trusted certificate
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Certificate'
responses:
'200':
description: Certificate created or updated.
/public/iam/v2/user:
get:
operationId: listUsers
tags:
- Users
summary: List organization users
security:
- bearerAuth: []
responses:
'200':
description: Users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/public/iam/v2/user/{userEmail}:
put:
operationId: upsertUser
tags:
- Users
summary: Create or update a user and their group membership
security:
- bearerAuth: []
parameters:
- name: userEmail
in: path
required: true
schema:
type: string
format: email
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: User created or updated.
delete:
operationId: deleteUser
tags:
- Users
summary: Delete a user
security:
- bearerAuth: []
parameters:
- name: userEmail
in: path
required: true
schema:
type: string
format: email
responses:
'204':
description: User deleted.
/public/iam/v2/group:
get:
operationId: listGroups
tags:
- Groups
summary: List groups
security:
- bearerAuth: []
responses:
'200':
description: Groups.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Group'
/public/iam/v2/group/{groupName}:
get:
operationId: getGroup
tags:
- Groups
summary: Get a group and its permissions
description: >-
Retrieves a group with its members and the granular RBAC permissions
attached to it. Permissions can be scoped to a single cluster or all
clusters and reference topic patterns and Kafka resource types.
security:
- bearerAuth: []
parameters:
- name: groupName
in: path
required: true
schema:
type: string
example: project-a
responses:
'200':
description: The group and its permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
put:
operationId: upsertGroup
tags:
- Groups
summary: Create or update a group and its permissions
security:
- bearerAuth: []
parameters:
- name: groupName
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
responses:
'200':
description: Group created or updated.
delete:
operationId: deleteGroup
tags:
- Groups
summary: Delete a group
security:
- bearerAuth: []
parameters:
- name: groupName
in: path
required: true
schema:
type: string
responses:
'204':
description: Group deleted.
/public/self-serve/v1/application:
get:
operationId: listApplications
tags:
- Self-Service
summary: List Self-Service applications
security:
- bearerAuth: []
responses:
'200':
description: Applications.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Application'
put:
operationId: upsertApplication
tags:
- Self-Service
summary: Create or update a Self-Service Application resource
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Application'
responses:
'200':
description: Application created or updated.
/public/self-serve/v1/topic-policy:
put:
operationId: upsertTopicPolicy
tags:
- Self-Service
summary: Create or update a TopicPolicy resource
description: >-
Defines constraints on topic metadata labels and configuration values
(for example retention.ms or replicationFactor) using OneOf, Range, or
Match constraints. A TopicPolicy applies once it is referenced from an
ApplicationInstance via spec.topicPolicyRef.
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TopicPolicy'
responses:
'200':
description: Topic policy created or updated.
/gateway/v2/interceptor:
get:
operationId: listInterceptors
tags:
- Interceptors
summary: List Gateway interceptors
security:
- basicAuth: []
responses:
'200':
description: Interceptors.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Interceptor'
put:
operationId: upsertInterceptor
tags:
- Interceptors
summary: Create or update a Gateway interceptor
description: >-
Creates or updates an interceptor that applies a plugin (for example
data quality, encryption, safeguard, or chargeback) to Kafka traffic
flowing through the Gateway, optionally scoped to a virtual cluster,
group, or username.
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Interceptor'
responses:
'200':
description: Interceptor created or updated.
/gateway/v2/virtual-cluster:
put:
operationId: upsertVirtualCluster
tags:
- Virtual Clusters
summary: Create or update a Gateway virtual cluster
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualCluster'
responses:
'200':
description: Virtual cluster created or updated.
/gateway/v2/virtual-cluster/{name}:
get:
operationId: getVirtualCluster
tags:
- Virtual Clusters
summary: Get a virtual cluster
description: >-
Returns the virtual cluster definition including its bootstrap address
and recommended client properties.
security:
- basicAuth: []
parameters:
- name: name
in: path
required: true
schema:
type: string
responses:
'200':
description: The virtual cluster.
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualCluster'
/gateway/v2/service-account:
put:
operationId: upsertServiceAccount
tags:
- Virtual Clusters
summary: Create or update a Gateway service account
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccount'
responses:
'200':
description: Service account created or updated.
/gateway/v2/token:
post:
operationId: createToken
tags:
- Virtual Clusters
summary: Generate an authentication token for a service account
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Generated token.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Console API key generated by an admin in Settings > API Keys, passed as
Authorization: Bearer $ADMIN_API_KEY.
basicAuth:
type: http
scheme: basic
description: >-
Gateway admin credentials (GATEWAY_ADMIN_API_USERS), passed as HTTP
Basic authentication to the Gateway admin API.
schemas:
KafkaCluster:
type: object
properties:
apiVersion:
type: string
example: v1
kind:
type: string
example: KafkaCluster
metadata:
type: object
properties:
name:
type: string
spec:
type: object
properties:
displayName:
type: string
bootstrapServers:
type: string
color:
type: string
ignoreUntrustedCertificate:
type: boolean
properties:
type: object
additionalProperties:
type: string
schemaRegistry:
type: object
Certificate:
type: object
properties:
name:
type: string
certificate:
type: string
description: PEM-encoded certificate chain.
User:
type: object
properties:
apiVersion:
type: string
example: iam/v2
kind:
type: string
example: User
metadata:
type: object
properties:
name:
type: string
format: email
spec:
type: object
properties:
firstName:
type: string
lastName:
type: string
permissions:
type: array
items:
$ref: '#/components/schemas/Permission'
Group:
type: object
properties:
apiVersion:
type: string
example: iam/v2
kind:
type: string
example: Group
metadata:
type: object
properties:
name:
type: string
spec:
type: object
properties:
displayName:
type: string
description:
type: string
externalGroups:
type: array
items:
type: string
members:
type: array
items:
type: string
permissions:
type: array
items:
$ref: '#/components/schemas/Permission'
Permission:
type: object
properties:
resourceType:
type: string
description: Kafka resource type the permission applies to.
example: TOPIC
name:
type: string
description: Topic or resource name or pattern.
example: project-a-*
patternType:
type: string
enum:
- LITERAL
- PREFIXED
cluster:
type: string
description: Cluster id, or omitted/'*' for all clusters.
permissions:
type: array
items:
type: string
example:
- topicViewConfig
- topicConsume
- topicProduce
Application:
type: object
properties:
apiVersion:
type: string
example: self-serve/v1
kind:
type: string
example: Application
metadata:
type: object
properties:
name:
type: string
spec:
type: object
properties:
title:
type: string
description:
type: string
owner:
type: string
TopicPolicy:
type: object
properties:
apiVersion:
type: string
example: self-serve/v1
kind:
type: string
example: TopicPolicy
metadata:
type: object
properties:
name:
type: string
spec:
type: object
properties:
policies:
type: object
description: >-
Map of metadata labels and topic configuration keys to
constraints (OneOf, Range, Match, etc.).
additionalProperties: true
Interceptor:
type: object
properties:
apiVersion:
type: string
example: gateway/v2
kind:
type: string
example: Interceptor
metadata:
type: object
properties:
name:
type: string
scope:
type: object
properties:
vCluster:
type: string
group:
type: string
username:
type: string
spec:
type: object
properties:
comment:
type: string
pluginClass:
type: string
example: io.conduktor.gateway.interceptor.safeguard.ProduceRateLimitingPolicyPlugin
priority:
type: integer
config:
type: object
additionalProperties: true
VirtualCluster:
type: object
properties:
apiVersion:
type: string
example: gateway/v2
kind:
type: string
example: VirtualCluster
metadata:
type: object
properties:
name:
type: string
spec:
type: object
properties:
aclEnabled:
type: boolean
superUsers:
type: array
items:
type: string
bootstrapServers:
type: string
ServiceAccount:
type: object
properties:
apiVersion:
type: string
example: gateway/v2
kind:
type: string
example: GatewayServiceAccount
metadata:
type: object
properties:
name:
type: string
vCluster:
type: string
spec:
type: object
properties:
type:
type: string
enum:
- LOCAL
- EXTERNAL
externalNames:
type: array
items:
type: string
TokenRequest:
type: object
properties:
username:
type: string
vCluster:
type: string
lifeTimeSeconds:
type: integer
TokenResponse:
type: object
properties:
token:
type: string