Roles
delete
Deletes a role.
Authorizations
Path parameters
namestringRequired
Responses
204
Successful deletion.
No content
default
Error object.
application/json
delete
DELETE /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
patch
Updates a role.
Authorizations
Path parameters
namestringRequired
Body
Updates a role. Absent fields are left untouched.
display_namestring · min: 1 · max: 150Optional
Updates the display name of the role.
Responses
200
Happy response.
application/json
default
Error object.
application/json
patch
PATCH /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 145
{
"display_name": "text",
"policy": [
{
"action": "kafka:ListTopics",
"resource": "text",
"effect": "allow"
}
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-09-01T03:05:12.243Z",
"policy": [
{
"action": "kafka:ListTopics",
"resource": "text",
"effect": "allow"
}
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
get
Returns a specific role.
Authorizations
Path parameters
namestringRequired
Responses
200
Happy response.
application/json
default
Error object.
application/json
get
GET /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-09-01T03:05:12.243Z",
"policy": [
{
"action": "kafka:ListTopics",
"resource": "text",
"effect": "allow"
}
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
post
Creates a new role.
Authorizations
Body
Contains the fields needed to create a role.
namestring · hq-resource-name · min: 1 · max: 63Required
Sets the unique name of the new role. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.
display_namestring · min: 1 · max: 150Optional
Sets the display name of the new role. If not provided, the value of "name" will be used.
Responses
201
Happy response.
application/json
default
Error object.
application/json
post
POST /api/v1/roles HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 159
{
"name": "text",
"display_name": "text",
"policy": [
{
"action": "kafka:ListTopics",
"resource": "text",
"effect": "allow"
}
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-09-01T03:05:12.243Z",
"policy": [
{
"action": "kafka:ListTopics",
"resource": "text",
"effect": "allow"
}
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
get
Returns all roles.
Authorizations
Responses
200
Happy response.
application/json
default
Error object.
application/json
get
GET /api/v1/roles HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-09-01T03:05:12.243Z",
"policy_length": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}
Last updated
Was this helpful?