roles

Creates, updates, deletes, gets or lists a roles resource.

Overview

Name	roles
Type	Resource
Id	clickhouse.clickstack.roles

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Role ID. (example: 507f1f77bcf86cd799439011)
name	string	Role name. (example: Read Only)
created_at	string (date-time)	Creation timestamp. (example: 2025-01-01T00:00:00.000Z) (wire: createdAt)
description	string	Human-readable role description. (example: Read-only access to all resources)
is_predefined	boolean	Whether this is an immutable predefined/system role. (wire: isPredefined)
permissions	array	The CASL permissions granted by this role.
updated_at	string (date-time)	Last update timestamp. (example: 2025-06-15T10:30:00.000Z) (wire: updatedAt)

list

Name	Datatype	Description
id	string	Role ID. (example: 507f1f77bcf86cd799439011)
name	string	Role name. (example: Read Only)
created_at	string (date-time)	Creation timestamp. (example: 2025-01-01T00:00:00.000Z) (wire: createdAt)
description	string	Human-readable role description. (example: Read-only access to all resources)
is_predefined	boolean	Whether this is an immutable predefined/system role. (wire: isPredefined)
permissions	array	The CASL permissions granted by this role.
updated_at	string (date-time)	Last update timestamp. (example: 2025-06-15T10:30:00.000Z) (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	service_id, click_stack_role_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a specific role by ID.
list	select	service_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves all roles for the authenticated team, including predefined roles.
create	insert	service_id, organization_id, name, permissions		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Creates a new custom role for the team.
update	update	service_id, click_stack_role_id, organization_id, permissions		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Updates a custom role's permissions, name, and description. Predefined roles cannot be modified.
delete	delete	service_id, click_stack_role_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Deletes a custom role. Predefined roles, the team default user role, and roles assigned to users cannot be deleted.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
click_stack_role_id	string	id parameter (wire: clickStackRoleId)
organization_id	string	ClickHouse Cloud organization ID. Resolved from the CLICKHOUSE_ORG_ID environment variable when it is set (x-stackQL-envVar); otherwise it must be supplied on every query as WHERE organization_id = <uuid>. A WHERE value always takes precedence over the environment. (x-stackQL-envVar: CLICKHOUSE_ORG_ID)
service_id	string (uuid)	ID of the ClickStack service. (wire: serviceId)

SELECT examples

get

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a specific role by ID.

SELECT
id,
name,
created_at,
description,
is_predefined,
permissions,
updated_at
FROM clickhouse.clickstack.roles
WHERE service_id = '{{ service_id }}' -- required
AND click_stack_role_id = '{{ click_stack_role_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

list

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves all roles for the authenticated team, including predefined roles.

SELECT
id,
name,
created_at,
description,
is_predefined,
permissions,
updated_at
FROM clickhouse.clickstack.roles
WHERE service_id = '{{ service_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

INSERT examples

create

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Creates a new custom role for the team.

INSERT INTO clickhouse.clickstack.roles (
name,
description,
permissions,
service_id,
organization_id
)
SELECT 
'{{ name }}' /* required */,
'{{ description }}',
'{{ permissions }}' /* required */,
'{{ service_id }}',
'{{ organization_id }}'
RETURNING
request_id,
result,
status
;

Manifest

# Description fields are for documentation purposes
- name: roles
props:
  - name: service_id
    value: "{{ service_id }}"
    description: Required parameter for the roles resource.
  - name: organization_id
    value: "{{ organization_id }}"
    description: Required parameter for the roles resource.
  - name: name
    value: "{{ name }}"
    description: |
      Role name. Must be unique within the team and not collide with a predefined role.
  - name: description
    value: "{{ description }}"
    description: |
      Human-readable role description.
  - name: permissions
    description: |
      The CASL permissions to grant to the role.
    value:
      - action: "{{ action }}"
        subject: "{{ subject }}"
        inverted: {{ inverted }}
        integration: "{{ integration }}"
        conditions: "{{ conditions }}"

UPDATE examples

update

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Updates a custom role's permissions, name, and description. Predefined roles cannot be modified.

UPDATE clickhouse.clickstack.roles
SET 
name = '{{ name }}',
description = '{{ description }}',
permissions = '{{ permissions }}'
WHERE 
service_id = '{{ service_id }}' --required
AND click_stack_role_id = '{{ click_stack_role_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
AND permissions = '{{ permissions }}' --required
RETURNING
request_id,
result,
status;

DELETE examples

delete

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Deletes a custom role. Predefined roles, the team default user role, and roles assigned to users cannot be deleted.

DELETE FROM clickhouse.clickstack.roles
WHERE service_id = '{{ service_id }}' --required
AND click_stack_role_id = '{{ click_stack_role_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
;