Lenses Docs

Returns all roles.

get

/v1/roles

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-11T07:21:19.164Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Creates a new role.

post

/v1/roles

Authorizations

Body

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: 150

Sets the display name of the new role. If not provided, the value of "name" will be used.

policyobject[]required

Describes the effect for an action and resource.

metadataobject

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-11T07:21:19.164Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

Returns a specific role.

get

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-11T07:21:19.164Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

Updates a role.

patch

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Body

display_namestring · min: 1 · max: 150

Updates the display name of the role.

policyobject[]

Describes the effect for an action and resource.

metadataobject

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-11T07:21:19.164Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

Deletes a role.

delete

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

Roles

Roles

Roles

Roles

Show child attributes

Show child attributes

Show child attributes

Show child attributes