IRPCLogin.LogIn
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 MFiles.IRPCLogin |
|---|---|
| gRPC method | /MFiles.IRPCLogin/LogIn |
| HTTP (mf-http-grpc) | POST /grpc/v1/log-in |
| Request | LogInRequest |
| Response | LogInResponse |
| 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) |
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 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 instead.
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 | 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 | 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 | 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 | 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. |
client_data | ClientData | 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 | 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, empty means the language of the existing session. |
client_data.type | ClientType | 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 | 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 | How the caller proves its identity: type plus the matching member of data. |
authentication_data.type | AuthDataType | 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 | The method's data. Set exactly the member that type names. |
authentication_data.data.mfiles_leg1 | AuthDataClientUnion.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 (oneof data) | Second call of the two-step M-Files challenge login (AUTH_DATA_TYPE_MFILES_LEG2). |
authentication_data.data.windows | AuthDataClientUnion.WindowsData (oneof data) | Windows authentication tokens (AUTH_DATA_TYPE_WINDOWS), possibly over several calls. |
authentication_data.data.plugin | AuthDataClientUnion.PluginData (oneof data) | Authentication through a plug-in such as single sign-on (AUTH_DATA_TYPE_PLUGIN). |
authentication_data.data.credentials | Credentials (oneof data) | User name and password (AUTH_DATA_TYPE_CREDENTIALS). Completes in one call. |
authentication_data.data.anonymous | AuthDataClientUnion.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. |
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 | 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 | 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 | Method-specific reply: a challenge, a token to pass on, or nothing. |
authentication_data.authentication_attempt_identifier | AuthenticationAttemptIdentifier | 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 | 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 | What the session may do on server level and in the vault, regardless of object permissions. |
session_data.server_vault_capabilities | ServerVaultCapabilities | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than GetServerCapabilities. |
session_data.locale | uint32 | The Windows locale ID used for sorting, for example 1033. |
session_data.keep_alive_interval_in_seconds | uint32 | Call KeepAlive 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 | The edition of the server license.Values: PRODUCT_MODE_FULL (0), PRODUCT_MODE_EXPRESS (1), PRODUCT_MODE_BUSINESS (2). |
session_data.vault_data | VaultData | The user's identity in the vault. Unset for a server-level session. |
session_data.account_type | AccountType | 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 | The server's license serial number and deployment type. |
session_data.license_type | LicenseType | 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 | 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 | Vaults that are online and visible to the user. |
vaults_availability.vaults_offline[] | repeated VaultBasic | Vaults that are offline (for example under maintenance) and visible to the user. |
vaults_availability.ground_link_proxies_online[] | repeated VaultBasic | Online Ground Link proxy vaults. |
vaults_availability.ground_link_proxies_offline[] | repeated VaultBasic | Offline Ground Link proxy vaults. |
Related methods
- KeepAlive -- Tells the server that the session is still in use, so that it does not expire.
- IRPCVaults.GetVaults -- Lists the vaults on the server that the session's user can see.
- LogInWithSession -- Opens a new session to a vault (or the server) for the user of an existing session, without authenticating again.
- LogInRemote -- Logs in (with authentication) to a remote server.