# User & Role Operations

Look up TypeScript methods for managing Milvus users and passwords, assigning roles, and granting or revoking privileges.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/

## Section links

- [User lifecycle](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#user-lifecycle)
- [createUser](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#createuser)
- [updateUser](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#updateuser)
- [deleteUser](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#deleteuser)
- [listUsers](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#listusers)
- [describeUser](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#describeuser)
- [Role lifecycle](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#role-lifecycle)
- [createRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#createrole)
- [dropRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#droprole)
- [listRoles](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#listroles)
- [describeRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#describerole)
- [hasRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#hasrole)
- [dropAllRoles](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#dropallroles)
- [User-role assignment](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#user-role-assignment)
- [addUserToRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#addusertorole)
- [removeUserFromRole](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#removeuserfromrole)
- [Legacy privilege APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#legacy-privilege-apis)
- [grantPrivilege](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#grantprivilege)
- [revokePrivilege](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#revokeprivilege)
- [selectGrant](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#selectgrant)
- [listGrants](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#listgrants)
- [Privilege groups](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#privilege-groups)
- [createPrivilegeGroup](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#createprivilegegroup)
- [dropPrivilegeGroup](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#dropprivilegegroup)
- [listPrivilegeGroups](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#listprivilegegroups)
- [addPrivilegesToGroup](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#addprivilegestogroup)
- [removePrivilegesFromGroup](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#removeprivilegesfromgroup)
- [RBAC v2 privilege APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#rbac-v2-privilege-apis)
- [grantPrivilegeV2](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#grantprivilegev2)
- [revokePrivilegeV2](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#revokeprivilegev2)
- [RBAC backup and restore](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#rbac-backup-and-restore)
- [backupRBAC](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#backuprbac)
- [restoreRBAC](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#restorerbac)
- [Common RBAC types](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#common-rbac-types)
- [Minimal setup flow](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#minimal-setup-flow)
- [HTTP client user APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#http-client-user-apis)
- [Related](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#related)

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.

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

## User lifecycle

### createUser

Create a credentialed Milvus user.

```typescript
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:

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

### updateUser

Update a user’s password.

```typescript
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:

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

### deleteUser

Delete a Milvus user.

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

**Parameters**:

- `username`: User name.
- `timeout?`: Request timeout in milliseconds.

Example:

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

### listUsers

List credentialed users.

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

**Response**:

- `status`: Response status.
- `usernames`: User names.

Example:

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

### describeUser

Describe a user and optionally include role information.

```typescript
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:

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

## Role lifecycle

### createRole

Create a role.

```typescript
createRole(data: CreateRoleReq): Promise<ResStatus>
```

**Parameters**:

- `roleName`: Role name.
- `timeout?`: Request timeout in milliseconds.

Example:

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

### dropRole

Drop a role.

```typescript
dropRole(data: DropRoleReq): Promise<ResStatus>
```

**Parameters**:

- `roleName`: Role name.
- `timeout?`: Request timeout in milliseconds.

Example:

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

### listRoles

List roles, optionally including assigned users.

```typescript
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:

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

### describeRole

Describe one role, optionally including assigned users and grants.

```typescript
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:

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

### hasRole

Check whether a role exists.

```typescript
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:

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

### dropAllRoles

Drop every role after revoking grants for each role.

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

Use this only in cleanup scripts or test environments.

## User-role assignment

### addUserToRole

Assign a user to a role.

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

**Parameters**:

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

Example:

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

### removeUserFromRole

Remove a user from a role.

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

**Parameters**:

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

Example:

```typescript
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](https://milvus-io.github.io/milvus-sdk-node/api-reference/users-roles/#rbac-v2-privilege-apis) when possible.

### grantPrivilege

Grant a privilege to a role.

```typescript
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:

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

### revokePrivilege

Revoke a privilege from a role.

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

Example:

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

### selectGrant

Get grants for one role/object pair.

```typescript
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.

```typescript
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**:

```typescript
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

```typescript
createPrivilegeGroup(data: CreatePrivilegeGroupReq): Promise<ResStatus>
```

**Parameters**:

- `group_name`: Privilege group name.
- `timeout?`: Request timeout in milliseconds.

### dropPrivilegeGroup

```typescript
dropPrivilegeGroup(data: DropPrivilegeGroupReq): Promise<ResStatus>
```

**Parameters**:

- `group_name`: Privilege group name.
- `timeout?`: Request timeout in milliseconds.

### listPrivilegeGroups

```typescript
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

```typescript
addPrivilegesToGroup(data: AddPrivilegesToGroupReq): Promise<ResStatus>
```

**Parameters**:

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

Example:

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

### removePrivilegesFromGroup

```typescript
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.

```typescript
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:

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

### revokePrivilegeV2

Revoke a scoped privilege from a role.

```typescript
revokePrivilegeV2(data: RevokePrivilegeV2Request): Promise<ResStatus>
```

Example:

```typescript
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.

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

**Response**:

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

### restoreRBAC

Restore RBAC metadata returned by `backupRBAC`.

```typescript
restoreRBAC(data: RestoreRBACRequest): Promise<ResStatus>
```

**Parameters**:

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

## Common RBAC types

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- [User & Role Management guide](https://milvus-io.github.io/milvus-sdk-node/management/user-role-management/)
- [Types & Enums](https://milvus-io.github.io/milvus-sdk-node/api-reference/types-and-enums/)
