Roles

Returns all roles.

GEThttps://api.example.com/api/v1/roles

Response

200default

Happy response.

Body

application/json

items*array of CompactRole (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:57:40.382Z",
      "policy_length": 0
    }
  ]
}

Creates a new role.

POSThttps://api.example.com/api/v1/roles

Body

application/json

name*string (hq-resource-name)

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

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

policy*array of PermissionStatement (object)

Contains a list of permission statements.

metadataMetadata (object)

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

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

Response

201default

Happy response.

Body

application/json

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "policy": [
        {
          "action": "kafka:ListTopics",
          "resource": "text",
          "effect": "allow"
        }
      ]
    }),
});
const data = await response.json();

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T13:57:40.382Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Returns a specific role.

GEThttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles/{name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T13:57:40.382Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Updates a role.

PATCHhttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the role.

policyarray of PermissionStatement (object)

Sets, if specififed, the new permission statements.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

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

Response

200default

Happy response.

Body

application/json

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles/{name}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T13:57:40.382Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Deletes a role.

DELETEhttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles/{name}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

default

{
  "type": "not_found",
  "title": "text",
  "status": 0,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}