# IRPCLogin.LogIn

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)

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

Badges: `Vault API / core` `session` `no session`

Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is
all zeros.

- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LogIn`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-in`
- **Request:** [`LogInRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md#request)
- **Response:** [`LogInResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

Needs no session. The session ID comes back in `session_data.session_id` (48 bytes) and goes,
unchanged, into the `mfiles-session-id-bin` header of all later calls.

**User name and password** (`AUTH_DATA_TYPE_CREDENTIALS`) complete in one call. Set
`authentication_data.type` and fill `authentication_data.data.credentials`; the type and the
populated union member must match, an unset type fails with `E_INVALIDARG`. Use this over TLS
only: the password is sent as is.

**Multi-step methods** (Windows authentication, plug-in authentication, the two-leg M-Files
challenge) may need several calls. While the response has no `session_data`, the login is not
done: call `LogIn` again with the next authentication data and the
`authentication_attempt_identifier` from the previous response, placed in the union member's own
`authentication_attempt_identifier` field. The attempt is discarded when it completes or fails.

**Vault GUID.** `login_data.vault_guid` accepts the GUID with or without braces, in any case.
An empty string is not "no vault": it fails with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. Use
`{00000000-0000-0000-0000-000000000000}` for a server-level session. An unknown GUID fails with
`E_MFILES_UNKNOWN_VAULT`; an offline vault with `E_MFILES_VAULT_OFFLINE`.

**Failures.** An unknown user, a wrong password and a login blocked by the server's login attack
protection are all reported as `E_MFILES_AUTHENTICATION_FAILED` (`Authentication failed.`)
without further detail. Do not retry a failed login in a loop. A missing user name fails with
`E_INVALIDARG`.

**Session lifetime.** The session expires when no
[KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) arrives for twice
`session_data.keep_alive_interval_in_seconds`; other calls do not extend it.

`vaults_availability` is filled only for a server-level login on servers that enable it; expect it
to be empty and use [GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md) instead.

<a id="request"></a>

## Request: LogInRequest

A structure that specifies the request type for the LogInRequest method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `environment_data` | [`EnvironmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EnvironmentData/index.md) | Describes the client device. Optional; `client_name` is shown as the session's computer name. |
| `environment_data.client_name` | `string` | A name for the client device, such as its host name. Shown as the session's computer name. Must not start with `@{`. |
| `environment_data.timezone` | [`TimeZoneInformation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TimeZoneInformation/index.md) | The client device's time zone. Leave unset if unknown. |
| `environment_data.timezone.bias_in_minutes` | `int32` | The difference between UTC and local time, in minutes. |
| `environment_data.timezone.standard_name` | `string` | A description for standard time, max length 31. |
| `environment_data.timezone.standard_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from daylight saving time to standard time occurs. |
| `environment_data.timezone.standard_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during standard time. |
| `environment_data.timezone.daylight_name` | `string` | A description for daylight saving time (DST), max length 31. |
| `environment_data.timezone.daylight_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from standard time to daylight saving time occurs. |
| `environment_data.timezone.daylight_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during daylight saving time. |
| `environment_data.host_platform` | `string` | Free-form description of the platform, for example `Windows 11` or `Python 3.13`. |
| `environment_data.device_token` | `string` | A stable, globally unique identifier of the device. Used by M-Files clients that register devices; see [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md). |
| `client_data` | [`ClientData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientData/index.md) | Describes the client software. Set `type` (for example `CLIENT_TYPE_SERVER_API`) and `language`; set `capabilities` only for features your code handles. |
| `client_data.version` | `uint64` | The client's version, packed like `QueryVersionResponse.server_version` (`major << 48 \| minor << 32 \| build << 16 \| patch`). May be 0. If the server administrator has set a minimum client version, older clients are refused with `E_MFILES_INCOMPATIBLE_SERVER_VERSION`. |
| `client_data.capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Features the client software handles. The server adapts some responses to them, so set only the flags your code implements; leave the rest false. |
| `client_data.capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `client_data.capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `client_data.capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `client_data.capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `client_data.capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `client_data.capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `client_data.capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `client_data.capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `client_data.capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `client_data.capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `client_data.capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `client_data.capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `client_data.capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `client_data.capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `client_data.capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `client_data.capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `client_data.capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `client_data.capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `client_data.capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `client_data.capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `client_data.capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `client_data.capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `client_data.capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `client_data.capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `client_data.capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `client_data.capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `client_data.capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `client_data.capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `client_data.capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `client_data.capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `client_data.capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `client_data.capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `client_data.capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `client_data.capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `client_data.capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `client_data.capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `client_data.capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `client_data.capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |
| `client_data.language` | `string` | The client's language, for example `en`. For [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md), empty means the language of the existing session. |
| `client_data.type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | The kind of client. Applications use `CLIENT_TYPE_SERVER_API`. |
| `client_data.type_specifier` | `string` | Optional free-form name of the client application. |
| `login_data` | [`LoginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LoginData/index.md) | The target vault and session options. `vault_guid` is required; see Remarks. |
| `login_data.server_hostname` | `string` | The host name the client used to reach the server. Optional for user name and password logins. Anonymous logins, and server-level logins on servers with vault login accounts, use it to find the vault configured for that host name. |
| `login_data.vault_guid` | `string` | The vault to log in to, as a GUID string with or without braces, in any case. Use `{00000000-0000-0000-0000-000000000000}` for a server-level session; an empty string is rejected with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. |
| `login_data.is_administrative` | `bool` | True for administrative tools that manage the vault rather than work with documents, as M-Files Admin does. Applications leave it false. |
| `login_data.client_session_timeout_in_seconds` | `uint32` | Optional. Requests a longer idle timeout for a vault session. Honored only when it is at least the server's session timeout and at most 7 days (or the server timeout if that is longer); otherwise, and for server-level sessions, the server timeout applies. The effective value shows as `SessionData.keep_alive_interval_in_seconds`, which is half of it. |
| `authentication_data` | [`AuthDataClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClient/index.md) | How the caller proves its identity: `type` plus the matching member of `data`. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method. Must match the member set in `data`; unset fails with `E_INVALIDARG`. For user name and password use `AUTH_DATA_TYPE_CREDENTIALS`. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataClientUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md) | The method's data. Set exactly the member that `type` names. |
| `authentication_data.data.mfiles_leg1` | [`AuthDataClientUnion.MFilesLeg1Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg1Data) (oneof data) | First call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG1`). |
| `authentication_data.data.mfiles_leg2` | [`AuthDataClientUnion.MFilesLeg2Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg2Data) (oneof data) | Second call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG2`). |
| `authentication_data.data.windows` | [`AuthDataClientUnion.WindowsData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-WindowsData) (oneof data) | Windows authentication tokens (`AUTH_DATA_TYPE_WINDOWS`), possibly over several calls. |
| `authentication_data.data.plugin` | [`AuthDataClientUnion.PluginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-PluginData) (oneof data) | Authentication through a plug-in such as single sign-on (`AUTH_DATA_TYPE_PLUGIN`). |
| `authentication_data.data.credentials` | [`Credentials`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Credentials/index.md) (oneof data) | User name and password (`AUTH_DATA_TYPE_CREDENTIALS`). Completes in one call. |
| `authentication_data.data.anonymous` | [`AuthDataClientUnion.AnonymousData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-AnonymousData) (oneof data) | Anonymous login (`AUTH_DATA_TYPE_ANONYMOUS`), when the vault allows it. Has no data. |
| `authentication_data.certificate_proof` | `string` | Leave empty. Used only when the server requires client certificates. |
| `authentication_data.is_certificate_validated` | `bool` | Leave false. Set only by M-Files proxies that validate client certificates themselves. |

<a id="response"></a>

## Response: LogInResponse

A structure that specifies the response type for the LogIn method.

> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `authentication_data` | [`AuthDataServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServer/index.md) | The server's half of the authentication exchange. For multi-step methods it carries the next challenge, whether the login is done, and the attempt identifier to send back. For `AUTH_DATA_TYPE_CREDENTIALS` there is nothing to act on. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method, as in the request. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataServerUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServerUnion/index.md) | Method-specific reply: a challenge, a token to pass on, or nothing. |
| `authentication_data.authentication_attempt_identifier` | [`AuthenticationAttemptIdentifier`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthenticationAttemptIdentifier/index.md) | Identifies this login attempt. In multi-step methods, send it back in the next call, in the `authentication_attempt_identifier` field of the request's union member. Ignore it for `AUTH_DATA_TYPE_CREDENTIALS`. |
| `session_data` | [`SessionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionData/index.md) | The new session, set when the login is complete and unset while a multi-step login is still in progress. |
| `session_data.session_id` | `bytes` | The session ID (48 bytes). Send it unchanged in the `mfiles-session-id-bin` metadata header of every call that needs a session. |
| `session_data.account_name` | `string` | The login account name, with the case stored on the server. |
| `session_data.access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | What the session may do on server level and in the vault, regardless of object permissions. |
| `session_data.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md). |
| `session_data.locale` | `uint32` | The Windows locale ID used for sorting, for example 1033. |
| `session_data.keep_alive_interval_in_seconds` | `uint32` | Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) at least this often. It is half of the session's idle timeout. |
| `session_data.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_data.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | The edition of the server license. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_data.vault_data` | [`VaultData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultData/index.md) | The user's identity in the vault. Unset for a server-level session. |
| `session_data.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Whether the login account is an M-Files or a Windows account. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `session_data.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | The server's license serial number and deployment type. |
| `session_data.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license the session uses. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `session_data.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often (half of the upload session timeout). |
| `vaults_availability` | [`VaultsAvailabilityOnServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultsAvailabilityOnServer/index.md) | Online and offline vaults the user can see, only for a server-level login and only on servers that enable this; otherwise empty. |
| `vaults_availability.vaults_online[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Vaults that are online and visible to the user. |
| `vaults_availability.vaults_offline[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Vaults that are offline (for example under maintenance) and visible to the user. |
| `vaults_availability.ground_link_proxies_online[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Online Ground Link proxy vaults. |
| `vaults_availability.ground_link_proxies_offline[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Offline Ground Link proxy vaults. |

<a id="related"></a>

## Related methods

- [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md): Tells the server that the session is still in use, so that it does not expire.
- [IRPCVaults.GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md): Lists the vaults on the server that the session's user can see.
- [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md): Opens a new session to a vault (or the server) for the user of an existing session, without authenticating again.
- [LogInRemote](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md): Logs in (with authentication) to a remote server.