Roles

delete

Deletes a role.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

204

Successful deletion.

No content

default

Error object.

application/json

delete/v1/roles/{name}

HTTPcURLJavaScriptPython

DELETE /api/v1/roles/{name} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

patch

Updates a role.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

application/json

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

Bundles a list of permission statements with a name.

namestringRequired

Holds the unique name of this role.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

default

Error object.

application/json

patch/v1/roles/{name}

HTTPcURLJavaScriptPython

PATCH /api/v1/roles/{name} HTTP/1.1
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": "2026-07-14T16:14:48.254Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns a specific role.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

Bundles a list of permission statements with a name.

namestringRequired

Holds the unique name of this role.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

default

Error object.

application/json

get/v1/roles/{name}

HTTPcURLJavaScriptPython

GET /api/v1/roles/{name} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2026-07-14T16:14:48.254Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

post

Creates a new role.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

application/json

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

Bundles a list of permission statements with a name.

namestringRequired

Holds the unique name of this role.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

default

Error object.

application/json

post/v1/roles

HTTPcURLJavaScriptPython

POST /api/v1/roles HTTP/1.1
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": "2026-07-14T16:14:48.254Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns all roles.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Contains a list of CompactRoles.

default

Error object.

application/json

get/v1/roles

HTTPcURLJavaScriptPython

GET /api/v1/roles HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-07-14T16:14:48.254Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}