# Users (IRPCUsersAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/

Adds, reads, modifies and removes the user accounts of a vault: who may use the vault, with
which vault roles.

Use this interface to add, modify and delete user accounts in a vault.

A user account is always associated with a login. The login defines
the authentication type and password (if not a Windows login). The
user account in a vault just grants a login access to that vault
and specifies the vault-level roles of the user. The user account
has an ID that remains constant and is used to identify the user in
the database (such as 'Last modified by' entry of document). The
user account can be associated with a different login without changing
the user ID in the vault.

Use the IRPCLoginsAdmin and/or IRPCVaultLoginsAdmin interface to manage logins.

- **gRPC service:** `MFiles.IRPCUsersAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 11
- **Proto file:** [`mfiles/IRPCUsersAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCUsersAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for the Users node of a vault; administration scripts can use it
to provision users. All methods need a vault session whose user has the vault right
`manage_users` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); the write methods also need
`license_allows_modifications`. The vault role full control (and a system administrator's
`full_control_of_vaults`) grants both.

**Login accounts and user accounts.** M-Files separates *who can authenticate* from *who may use
a vault*:

| Account | Stored in | Managed with | What it holds |
| --- | --- | --- | --- |
| Server login account | The server | [IRPCLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) | [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md): account type (M-Files or Windows), user name, password, server roles, license type, full name, email. One login can be used in every vault of the server. |
| Vault login account | One vault | [IRPCVaultLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) | The same [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) message, valid for that vault only. Exists only on servers with vault login accounts enabled, such as M-Files Cloud. |
| User account | One vault | This service | [UserAccount](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md): the vault user ID, the login it belongs to (`login_name`) and the vault roles. |

- A login authenticates; a user account grants that login access to one vault. A login without a
  user account in the vault cannot open the vault.
- `UserAccount.login_name` is the login's account name: the user name of an M-Files login
  (`MikeT`) or the down-level logon name of a Windows login (domain and user name separated by a
  backslash).
- The user ID never changes. Objects refer to it (Created by, Last modified by, permissions), so
  pointing a user account to another login keeps all references.
- Managing server login accounts needs the system administrator server role (server right
  `manage_logins`); managing user accounts and vault login accounts needs only the vault right
  `manage_users`.

**Methods by task:**

- **Read:** [GetUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md),
  [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md),
  [SearchForUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md) (by login name).
- **Add or bring back:** [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) (preferred),
  [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md),
  [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md).
- **Change and remove:** [ModifyUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md),
  [RemoveUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md).
- **Follow changes:** [GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md).

Typical provisioning: make sure the login exists (server or vault login), then
[AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) with `login_name` set to the login's account
name, then add the user to groups with
[AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md).

Users who lack `manage_users` read users and groups through
[IRPCVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md), for example
[GetUsersAndUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md) and
[GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md).

**Accounts with an External ID.** `UserAccount.external_id` links the account to an identity in
an external system such as Microsoft Entra; identity synchronization (M-Files Manage) maintains
it. These methods cannot change it, and removing such an account can fail with "Access denied"
("... should be deleted via Manage").

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md) | Adds a user account, or brings back a removed one with the same login name. | `admin` `session` |
| [AddOrUndeleteUserViaADSync](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/index.md) | Adds a user account during a directory import; brings back a removed account only when the vault allows that. | `internal: not for applications` `admin` `session` |
| [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) | Adds a user account to the vault, or brings back a removed one. | `admin` `session` |
| [GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md) | Gets the user accounts that were added, changed or removed after a version token. | `admin` `session` |
| [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md) | Gets one user account by ID. | `admin` `session` |
| [GetUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md) | Gets all user accounts of the vault. | `admin` `session` `idempotent` |
| [IsVaultReadyForM365StoragePermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions/index.md) | Tells whether the vault meets the user identity precondition for projecting M-Files permissions to Microsoft 365 storage. | `internal: not for applications` `admin` `session` `idempotent` |
| [ModifyUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md) | Replaces the data of an existing user account. | `admin` `session` `idempotent` |
| [RemoveUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md) | Removes a user account from the vault. | `admin` `session` |
| [SearchForUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md) | Finds the user account of a login name. | `admin` `session` |
| [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md) | Brings back a removed user account, identified by its GUID in the Users value list. | `admin` `session` |