Skip to main content

Create Cloud Role (V2)

Creates a custom organization- or project-scoped Cloud ACL role.

Policy reference — allowed resourceType values and their combinations:

resourceType Privileges Requires resources Note
project_member view, create, modify, delete No
project_role view, create, modify, delete, grant No
project view, modify, delete No
security view, manage No
backup view, manage No
observability view, manage No
serving_cluster create, view, modify, delete Yes (except create) resources = cluster id, e.g. in01-xxx. Use * to cover all clusters including future ones.
on_demand_cluster create, view, modify, delete Yes (except create) resources = cluster id
volume create, view, modify, delete, usage Yes (except create) resources = volume id
storage_integration create, view, modify, delete, usage Yes (except create) resources = integration id
model_provider_integration create, view, modify, delete, usage Yes (except create) resources = integration id
kms_integration create, view, modify, delete, usage Yes (except create) resources = integration id (CMEK)
datadog_integration create, view, modify, delete, usage Yes (except create) resources = integration id
serving_cluster_data read, write, all Yes resources = cluster id
on_demand_compute_data read, write, all No
volume_data read, write, all Yes resources = volume id
POST/v2/roles
Connection Endpoint

The base URL for this API is in the following format:

https://api.cloud.zilliz.com

📘Notes

The endpoints on the control plane currently supports up to 20 requests per second per user per endpoint.

shell
export BASE_URL="https://api.cloud.zilliz.com"
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges.

Example Value: Bearer {{TOKEN}}
Request Bodyapplication/json
projectIdstring

The project ID for a project-scoped role. Omit this field for an organization-scoped role.

roleNamestringrequired

The unique role display name within its scope.

descriptionstring

The optional role description.

policiesarrayrequired

The policy statements assigned to the role.

[]policiesobjectrequired

A policy statement attached to a custom Cloud role.

resourceTypestringrequired

The second-level resource the statement targets. Organization-level types: org_member, group, api_key, org_role, project_role, project, billing, authentication, org_control_ops, recovery. Project-level types: project_member, security, backup, observability, serving_cluster, on_demand_cluster, volume, storage_integration, model_provider_integration, kms_integration, datadog_integration, serving_cluster_data, on_demand_compute_data, volume_data.

privilegesarrayrequired

Atomic privileges on that resource, e.g. ["view", "create"].

[]privilegesstring
(To be added soon)
resourcesarray

Which instances the statement covers: * for all, or explicit ids (validated against the role's project). Required on serving_cluster, on_demand_cluster, volume, serving_cluster_data, volume_data, storage_integration, model_provider_integration, kms_integration and datadog_integration, unless the statement's only privilege is create. For on_demand_compute_data, predefined roles return ["*"]; on write this field is rejected and should be omitted. Everywhere else, omit it — it is rejected on write and never returned.

[]resourcesstring
(To be added soon)
scopeobject

Reserved for future use. Omit this field.

bash
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/roles" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "Org Manager",
    "description": "Can view members and manage org roles",
    "policies": [
        {
            "resourceType": "org_member",
            "privileges": [
                "view"
            ]
        },
        {
            "resourceType": "org_role",
            "privileges": [
                "grant",
                "manage"
            ]
        }
    ]
}'
bash
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/roles" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxx",
    "roleName": "Data Reader",
    "description": "Can read serving clusters",
    "policies": [
        {
            "resourceType": "serving_cluster",
            "resources": [
                "*"
            ],
            "privileges": [
                "view"
            ]
        }
    ]
}'
Responses200 OK - application/json

Returns a successful result or an error message.

A successful response.

codeintegerrequired

The response code.

Example Value: 0
dataobjectrequired

A Cloud ACL role.

roleIdstringrequired

The role ID.

roleNamestringrequired

The role display name.

roleTypestringrequired

The role scope.

roleKindstringrequired

Whether the role is predefined or custom.

projectIdstring

The project ID for a project-scoped role. For an organization-scoped role, this field returns an empty string.

descriptionstring

The role description.

policiesarray

The policy statements attached to the role.

[]policiesobject

A policy statement attached to a custom Cloud role.

resourceTypestringrequired

The second-level resource the statement targets. Organization-level types: org_member, group, api_key, org_role, project_role, project, billing, authentication, org_control_ops, recovery. Project-level types: project_member, security, backup, observability, serving_cluster, on_demand_cluster, volume, storage_integration, model_provider_integration, kms_integration, datadog_integration, serving_cluster_data, on_demand_compute_data, volume_data.

privilegesarrayrequired

Atomic privileges on that resource, e.g. ["view", "create"].

[]privilegesstring
(To be added soon)
resourcesarray

Which instances the statement covers: * for all, or explicit ids (validated against the role's project). Required on serving_cluster, on_demand_cluster, volume, serving_cluster_data, volume_data, storage_integration, model_provider_integration, kms_integration and datadog_integration, unless the statement's only privilege is create. For on_demand_compute_data, predefined roles return ["*"]; on write this field is rejected and should be omitted. Everywhere else, omit it — it is rejected on write and never returned.

[]resourcesstring
(To be added soon)
scopeobject

Reserved for future use. Omit this field.

A failure response.

codeintegerrequired

The response code.

messagestringrequired

The error message.

Successjson
{
    "code": 0,
    "data": {
        "roleId": "r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "roleName": "Org Manager",
        "roleType": "org",
        "roleKind": "custom",
        "description": "Can view members and manage org roles",
        "policies": [
            {
                "resourceType": "org_member",
                "privileges": [
                    "view"
                ]
            },
            {
                "resourceType": "org_role",
                "privileges": [
                    "grant",
                    "manage"
                ]
            }
        ]
    }
}
Ctrl I