Skip to main content

List Cloud Role Principals (V2)

Lists users, groups, and API keys directly bound to a Cloud ACL role.

GET/v2/roles/{roleId}/principals
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}}
roleIdstringpathrequired

The role ID.

Example Value: r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
projectIdstringquery

The project boundary for a predefined project role.

Example Value: proj-xxxxxxxx
currentPageintegerquery

The page number to return. The first page is 1.

Example Value: 1
pageSizeintegerquery

The number of items to return per page.

Example Value: 10
bash
export TOKEN="YOUR_API_KEY"
export roleId="r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

curl --request GET \
--url "${BASE_URL}/v2/roles/${roleId}/principals" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"
Responses200 OK - application/json

Returns a successful result or an error message.

A successful response.

codeintegerrequired

The response code.

Example Value: 0
dataobjectrequired
countintegerrequired

The total number of matching items.

currentPageintegerrequired

The current page number.

Value Range: ≥ 1
pageSizeintegerrequired

The requested page size.

Value Range: ≥ 1
principalsarrayrequired

The principals returned on this page.

[]principalsobjectrequired
principalTypestringrequired

The principal type.

principalIdstringrequired

The principal identifier. For user type, this is the user ID (e.g., usr-xxxxxxxxxxxxxxxxxxxxxx). For apikey type, this is the API key ID (64-character hex string). For group type, this is the group ID.

principalNamestringrequired

The display name of the principal.

assignedBystringrequired

The display name of the assigning user, or a raw non-user value such as system.

assignedAtstring<date-time>required

The assignment time in UTC ISO 8601 format.

A failure response.

codeintegerrequired

The response code.

messagestringrequired

The error message.

Successjson
{
    "code": 0,
    "data": {
        "count": 3,
        "currentPage": 1,
        "pageSize": 10,
        "principals": [
            {
                "principalType": "user",
                "email": "alice@example.com",
                "principalName": "Alice Wang",
                "assignedBy": "Bob Li",
                "assignedAt": "2026-06-21T00:00:00Z"
            },
            {
                "principalType": "group",
                "groupId": "g-xxxxxxxxxxxxxx",
                "principalName": "engineering",
                "assignedBy": "Bob Li",
                "assignedAt": "2026-06-21T00:00:00Z"
            },
            {
                "principalType": "apikey",
                "apiKeyId": "key-xxxxxxxxxxxxxx",
                "principalName": "Alice's key",
                "assignedBy": "system",
                "assignedAt": "2026-06-21T00:00:00Z"
            }
        ]
    }
}
Ctrl I