User & Role Operations

User and role APIs manage Milvus authentication and RBAC authorization. Most methods return ResStatus directly or a response object with a status field. Check error_code before relying on the returned data.

import {
  CollectionPrivileges,
  GlobalPrivileges,
  RbacObjects,
  UserPrivileges,
} from '@zilliz/milvus2-sdk-node';

User lifecycle

createUser

Create a credentialed Milvus user.

createUser(data: CreateUserReq): Promise<ResStatus>

Parameters:

• username: User name.
• password: User password. The SDK base64-encodes it before sending it to Milvus.
• timeout?: Request timeout in milliseconds.

Example:

await client.createUser({
  username: 'readonly_user',
  password: 'strong-password',
});

updateUser

Update a user’s password.

updateUser(data: UpdateUserReq): Promise<ResStatus>
updatePassword(data: UpdateUserReq): Promise<ResStatus> // alias

Parameters:

• username: User name.
• oldPassword: Current password.
• newPassword: New password.
• timeout?: Request timeout in milliseconds.

Example:

await client.updateUser({
  username: 'readonly_user',
  oldPassword: 'strong-password',
  newPassword: 'new-strong-password',
});

deleteUser

Delete a Milvus user.

deleteUser(data: DeleteUserReq): Promise<ResStatus>
dropUser(data: DeleteUserReq): Promise<ResStatus> // alias

Parameters:

• username: User name.
• timeout?: Request timeout in milliseconds.

Example:

await client.deleteUser({ username: 'readonly_user' });

listUsers

List credentialed users.

listUsers(data?: ListUsersReq): Promise<ListCredUsersResponse>

Response:

• status: Response status.
• usernames: User names.

Example:

const users = await client.listUsers();
console.log(users.usernames);

describeUser

Describe a user and optionally include role information.

describeUser(data: SelectUserReq): Promise<SelectUserResponse>
selectUser(data: SelectUserReq): Promise<SelectUserResponse> // alias

Parameters:

• username: User name.
• includeRoleInfo?: Include roles assigned to the user. Defaults to true in the SDK.
• timeout?: Request timeout in milliseconds.

Response:

• status: Response status.
• results[].user.name: User name.
• results[].roles[].name: Role names when role info is included.

Example:

const user = await client.describeUser({
  username: 'readonly_user',
  includeRoleInfo: true,
});

Role lifecycle

createRole

Create a role.

createRole(data: CreateRoleReq): Promise<ResStatus>

Parameters:

• roleName: Role name.
• timeout?: Request timeout in milliseconds.

Example:

await client.createRole({ roleName: 'readonly_role' });

dropRole

Drop a role.

dropRole(data: DropRoleReq): Promise<ResStatus>

Parameters:

• roleName: Role name.
• timeout?: Request timeout in milliseconds.

Example:

await client.dropRole({ roleName: 'readonly_role' });

listRoles

List roles, optionally including assigned users.

listRoles(data?: listRoleReq): Promise<SelectRoleResponse>

Parameters:

• includeUserInfo?: Include users assigned to each role. Defaults to true in the SDK.
• timeout?: Request timeout in milliseconds.

Response:

• status: Response status.
• results[].role.name: Role name.
• results[].users[].name: User names when user info is included.

Example:

const roles = await client.listRoles({ includeUserInfo: true });

describeRole

Describe one role, optionally including assigned users and grants.

describeRole(data: SelectRoleReq): Promise<SelectRoleResponse>
selectRole(data: SelectRoleReq): Promise<SelectRoleResponse> // alias

Parameters:

• roleName: Role name.
• includeUserInfo?: Include users assigned to the role. Defaults to true in the SDK.
• timeout?: Request timeout in milliseconds.

Response:

• status: Response status.
• results[].role.name: Role name.
• results[].users[].name: User names when user info is included.
• results[].entities: Grants attached to the role.

Example:

const role = await client.describeRole({
  roleName: 'readonly_role',
  includeUserInfo: true,
});

hasRole

Check whether a role exists.

hasRole(data: HasRoleReq): Promise<HasRoleResponse>

Parameters:

• roleName: Role name.
• timeout?: Request timeout in milliseconds.

Response:

• status: Response status from listRoles().
• hasRole: Whether the role exists.

Example:

const { hasRole } = await client.hasRole({ roleName: 'readonly_role' });

dropAllRoles

Drop every role after revoking grants for each role.

dropAllRoles(data?: GrpcTimeOut): Promise<ResStatus[]>

Use this only in cleanup scripts or test environments.

User-role assignment

addUserToRole

Assign a user to a role.

addUserToRole(data: AddUserToRoleReq): Promise<ResStatus>
grantRole(data: AddUserToRoleReq): Promise<ResStatus> // alias

Parameters:

• username: User name.
• roleName: Role name.
• timeout?: Request timeout in milliseconds.

Example:

await client.addUserToRole({
  username: 'readonly_user',
  roleName: 'readonly_role',
});

removeUserFromRole

Remove a user from a role.

removeUserFromRole(data: RemoveUserFromRoleReq): Promise<ResStatus>
revokeRole(data: RemoveUserFromRoleReq): Promise<ResStatus> // alias

Parameters:

• username: User name.
• roleName: Role name.
• timeout?: Request timeout in milliseconds.

Example:

await client.removeUserFromRole({
  username: 'readonly_user',
  roleName: 'readonly_role',
});

Legacy privilege APIs

These methods use the legacy OperatePrivilege request shape. For newer Milvus deployments, prefer RBAC v2 when possible.

grantPrivilege

Grant a privilege to a role.

grantPrivilege(data: OperateRolePrivilegeReq): Promise<ResStatus>
grantRolePrivilege(data: OperateRolePrivilegeReq): Promise<ResStatus> // alias

Parameters:

• roleName: Role name.
• object: Object type, such as RbacObjects.Collection, RbacObjects.Global, or RbacObjects.User.
• objectName: Object name. Use '*' for all matching objects when supported by Milvus.
• privilegeName: Privilege name, such as CollectionPrivileges.Search or GlobalPrivileges.CreateCollection.
• db_name?: Database name for the object.
• timeout?: Request timeout in milliseconds.

Example:

await client.grantPrivilege({
  roleName: 'readonly_role',
  object: RbacObjects.Collection,
  objectName: 'book_embeddings',
  privilegeName: CollectionPrivileges.Search,
});

revokePrivilege

Revoke a privilege from a role.

revokePrivilege(data: OperateRolePrivilegeReq): Promise<ResStatus>
revokeRolePrivilege(data: OperateRolePrivilegeReq): Promise<ResStatus> // alias

Example:

await client.revokePrivilege({
  roleName: 'readonly_role',
  object: RbacObjects.Collection,
  objectName: 'book_embeddings',
  privilegeName: CollectionPrivileges.Search,
});

selectGrant

Get grants for one role/object pair.

selectGrant(data: SelectGrantReq): Promise<SelectGrantResponse>
listGrant(data: SelectGrantReq): Promise<SelectGrantResponse> // alias

Parameters:

• roleName: Role name.
• object: Object type.
• objectName: Object name.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

listGrants

List grants for a role.

listGrants(data: ListGrantsReq): Promise<SelectGrantResponse>

Parameters:

• roleName: Role name.
• db_name?: Database name. Defaults to '*' in the SDK.
• timeout?: Request timeout in milliseconds.

Grant response shape:

type GrantEntity = {
  role: { name: string };
  object: { name: RbacObjects };
  object_name: string;
  grantor: {
    user: { name: string };
    privilege: { name: PrivilegesTypes };
  };
  db_name: string;
};

Privilege groups

Privilege groups let you define reusable sets of privilege names.

createPrivilegeGroup

createPrivilegeGroup(data: CreatePrivilegeGroupReq): Promise<ResStatus>

Parameters:

• group_name: Privilege group name.
• timeout?: Request timeout in milliseconds.

dropPrivilegeGroup

dropPrivilegeGroup(data: DropPrivilegeGroupReq): Promise<ResStatus>

Parameters:

• group_name: Privilege group name.
• timeout?: Request timeout in milliseconds.

listPrivilegeGroups

listPrivilegeGroups(data?: GrpcTimeOut): Promise<ListPrivilegeGroupsResponse>

Response:

• status: Response status.
• privilege_groups[].group_name: Privilege group name.
• privilege_groups[].privileges[].name: Privilege names in the group.

addPrivilegesToGroup

addPrivilegesToGroup(data: AddPrivilegesToGroupReq): Promise<ResStatus>

Parameters:

• group_name: Privilege group name.
• privileges: Array of privilege names.
• timeout?: Request timeout in milliseconds.

Example:

await client.addPrivilegesToGroup({
  group_name: 'read_only_collection',
  privileges: [
    CollectionPrivileges.Search,
    CollectionPrivileges.Query,
    GlobalPrivileges.DescribeCollection,
  ],
});

removePrivilegesFromGroup

removePrivilegesFromGroup(data: RemovePrivilegesFromGroupReq): Promise<ResStatus>

Parameters:

• group_name: Privilege group name.
• privileges: Array of privilege names.
• timeout?: Request timeout in milliseconds.

RBAC v2 privilege APIs

RBAC v2 grants privileges within an explicit database and collection scope. Use '*' for db_name or collection_name when you intentionally want a wildcard scope and your Milvus deployment supports it.

grantPrivilegeV2

Grant a privilege to a role in a database/collection scope.

grantPrivilegeV2(data: GrantPrivilegeV2Request): Promise<ResStatus>

Parameters:

• role: Role name.
• privilege: Privilege name.
• db_name: Database name or '*'.
• collection_name: Collection name or '*'.
• timeout?: Request timeout in milliseconds.

Example:

await client.grantPrivilegeV2({
  role: 'readonly_role',
  privilege: CollectionPrivileges.Search,
  db_name: 'default',
  collection_name: 'book_embeddings',
});

revokePrivilegeV2

Revoke a scoped privilege from a role.

revokePrivilegeV2(data: RevokePrivilegeV2Request): Promise<ResStatus>

Example:

await client.revokePrivilegeV2({
  role: 'readonly_role',
  privilege: CollectionPrivileges.Search,
  db_name: 'default',
  collection_name: 'book_embeddings',
});

RBAC backup and restore

backupRBAC

Back up RBAC metadata.

backupRBAC(data?: BackupRBACRequest): Promise<BackupRBACResponse>

Response:

• status: Response status.
• RBAC_meta: Users, roles, grants, and privilege groups.

restoreRBAC

Restore RBAC metadata returned by backupRBAC.

restoreRBAC(data: RestoreRBACRequest): Promise<ResStatus>

Parameters:

• RBAC_meta: RBAC metadata returned by backupRBAC.
• timeout?: Request timeout in milliseconds.

Common RBAC types

type RoleEntity = { name: string };
type User = { name: string };
type PrivilegeEntity = { name: PrivilegesTypes };

type RBACMeta = {
  users: User[];
  roles: RoleEntity[];
  grants: GrantEntity[];
  privilege_groups: PrivelegeGroup[];
};

Common object types:

enum RbacObjects {
  Collection = 'Collection',
  Global = 'Global',
  User = 'User',
}

Common privilege enums:

• CollectionPrivileges: collection-scoped privileges such as Load, Search, Query, Insert, Upsert, Delete, and CreatePartition.
• GlobalPrivileges: global privileges such as CreateCollection, DropCollection, CreateDatabase, and CreateResourceGroup.
• UserPrivileges: user privileges such as UpdateUser and SelectUser.
• PrivilegesTypes: union of collection, global, user, and custom privilege strings.

Minimal setup flow

await client.createUser({
  username: 'readonly_user',
  password: 'strong-password',
});

await client.createRole({ roleName: 'readonly_role' });
await client.addUserToRole({
  username: 'readonly_user',
  roleName: 'readonly_role',
});

await client.grantPrivilegeV2({
  role: 'readonly_role',
  privilege: CollectionPrivileges.Search,
  db_name: 'default',
  collection_name: 'book_embeddings',
});

HTTP client user APIs

The HTTP client exposes a smaller user-management surface:

createUser(params: HttpUserCreateReq, options?: FetchOptions): Promise<HttpBaseResponse>
updateUserPassword(params: HttpUserUpdatePasswordReq, options?: FetchOptions): Promise<HttpBaseResponse>
dropUser(params: HttpUserBaseReq, options?: FetchOptions): Promise<HttpBaseResponse>
describeUser(params: HttpUserBaseReq, options?: FetchOptions): Promise<HttpBaseResponse<string[]>>
listUsers(options?: FetchOptions): Promise<HttpBaseResponse<string[]>>
grantRoleToUser(params: HttpUserRoleReq, options?: FetchOptions): Promise<HttpBaseResponse>
revokeRoleFromUser(params: HttpUserRoleReq, options?: FetchOptions): Promise<HttpBaseResponse>

Related

• API Reference overview
• User & Role Management guide
• Types & Enums