Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Create a new role

View as MarkdownEdit this pageReport an issueSet up docs MCP
POST/v1/organizations/{organizationId}/roles

Creates a new custom role for an organization with specified policies and actors.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the requested organization.

    format: uuid

Request bodyJSON

  • namestringrequired

    Name of the role

  • actorsarray ofstringrequired

    List of actor resource IDs to assign to this role (e.g., ["user/uuid", "apiKey/uuid"])

  • policiesarray ofobjectrequired

    List of policies to create for this role

    4 properties
    • allowDenyALLOWorDENYrequired

      Whether this policy allows or denies access

    • permissionsarray ofstringrequired

      List of permissions to grant or deny (e.g., ["control-plane:organization:view"])

    • resourcesarray ofstringrequired

      List of resource IDs this policy applies to (e.g., ["instance/uuid", "instance/*"])

    • tagsoptionalobject
      2 properties
      • grantsoptionalarray ofstring

        Optional list of database grants (e.g., database names)

      • roleV2optionalsql-console-readonlyorsql-console-admin

        Optional SQL console role type

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    9 properties
    • idoptionalstring

      Unique role identifier

    • tenantIdoptionalstring

      Tenant resource ID (e.g., organization/uuid)

    • ownerIdoptionalstring

      Owner resource ID (e.g., organization/uuid)

    • nameoptionalstring

      Name of the role

    • typeoptionalsystemorcustom

      Whether this is a system role or a custom role

    • actorsoptionalarray ofstring

      List of actor resource IDs assigned to this role (e.g., user/uuid, apiKey/uuid)

    • policiesoptionalarray ofobject

      List of policies associated with this role

      7 properties
      • idoptionalstring

        Unique policy identifier

      • roleIdoptionalstring

        ID of the role this policy belongs to

      • tenantIdoptionalstring

        Tenant resource ID (e.g., organization/uuid)

      • allowDenyoptionalALLOWorDENY

        Whether this policy allows or denies access

      • permissionsoptionalarray ofstring

        List of permissions granted or denied by this policy

      • resourcesoptionalarray ofstring

        List of resource IDs this policy applies to (e.g., instance/uuid, instance/*)

      • tagsoptionalobject
        2 properties
        • grantsoptionalarray ofstring

          Optional list of database grants (e.g., database names)

        • roleV2optionalsql-console-readonlyorsql-console-admin

          Optional SQL console role type

    • createdAtoptionalstring

      Timestamp when the role was created. ISO-8601.

      format: date-time
    • updatedAtoptionalstring

      Timestamp when the role was last updated. ISO-8601.

      format: date-time
Navigation