# Login and sessions (IRPCLogin)

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)

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

An interface for handling client login & logout operations.

Use this interface to log in to MFServer and to maintain the login session.

- **gRPC service:** `MFiles.IRPCLogin`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 25
- **Proto file:** [`mfiles/IRPCLogin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLogin.proto)

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

## Overview

Opens, maintains and closes sessions. Almost every other call needs the session ID that
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) returns, sent as the binary metadata header
`mfiles-session-id-bin` (the 48 bytes of `session_data.session_id`, unchanged).

Which methods matter:

| Job | Methods |
|---|---|
| Find out how to authenticate | `GetServerCapabilities`, `GetAuthenticationConfiguration` |
| Open a session | `LogIn` (vault or server level), `LogInWithSession` (another vault, same user) |
| Keep it open | `KeepAlive`, at least every `session_data.keep_alive_interval_in_seconds` |
| Close it | `LogOut` |
| Inspect it | `GetVaultSessionInfo` |

Typical order:

1. [QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md) and
   [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md) (no session needed).
2. [GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md) when
   the vault may use single sign-on; `AUTH_METHOD_PLUGIN` means log in with
   `AUTH_DATA_TYPE_PLUGIN`, otherwise use user name and password (`AUTH_DATA_TYPE_CREDENTIALS`).
3. [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) with the vault GUID. Keep `session_data`.
4. Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) on a timer while the session is in use.
5. On `UNAUTHENTICATED`, log in again with `LogIn` and continue with the new session ID.
6. [LogOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md) when done. A session that is not logged out holds
   its license until it times out.

A session is bound to one vault, or to no vault (a server-level session, opened with the vault
GUID `{00000000-0000-0000-0000-000000000000}`). Methods that need a vault fail with
`E_MFILES_LOGIN_REQUIRED` when called with a server-level session.

Errors: an invalid, expired or missing session is reported as gRPC status `UNAUTHENTICATED` with
no error trailers. All other failures, including a wrong password, use status `UNKNOWN` with the
M-Files error stack in the `mfiles-error-serialized-bin` trailer.

Other methods of this service serve M-Files' own clients (licensing warnings, password
encryption, client settings, replication) and are marked as such.

Guides: [Authentication and sessions](https://developer.m-files.com/APIs/gRPC-API/runtime/authentication/index.md)
covers every login type and the session lifecycle, and
[Call metadata](https://developer.m-files.com/APIs/gRPC-API/runtime/call-metadata/index.md) the headers
that every call sends.

<a id="highlighted"></a>

## Highlighted methods

| Method | Summary | Facts |
|---|---|---|
| [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md) | Gets the features the server supports, without logging in. | `session` `no session` `idempotent` |
| [GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md) | Tells a client, before login, whether to authenticate with an authentication plug-in (single sign-on) and returns the plug-in's client-side configuration. | `session` `no session` `idempotent` |
| [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) | Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros. | `session` `no session` |
| [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. | `session` `session` |
| [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. | `session` `session` `idempotent` |
| [LogOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md) | Ends the session and releases its license. | `session` `session` |
| [GetVaultSessionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md) | Gets basic information about the current vault session: server version and ID, vault GUID and name, and the state of the server push channel. | `session` `session` `returns metadata structure version` |

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

## Other methods

| Method | Summary | Facts |
|---|---|---|
| [ChangePassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ChangePassword/index.md) | Changes the M-Files password of the logged-in account. | `session` `session` |
| [CreateUserSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/CreateUserSession/index.md) | Opens a session that acts as another user of the vault. | `session` `session` `idempotent` |
| [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md) | Removes a device registration (device token) of the logged-in user in the session's vault. | `session` `session` |
| [GetAuthenticationPlugins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationPlugins/index.md) | Lists the authentication plug-ins installed on the server, without their configurations. | `session` `no session` |
| [GetClientSettingsByType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetClientSettingsByType/index.md) | Gets client settings (theme, timeouts, banners, web security settings) for an M-Files web, desktop or Outlook client. | `session` `no session` |
| [GetLicenseExpirationInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLicenseExpirationInfo/index.md) | Gets the number of days until the server's license and its subscription expire. | `session` `session` `idempotent` |
| [GetLoginSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/index.md) | Gets the anonymous login settings and enabled vertical applications of the vault that serves the given host name, without a session. | `session` `no session` |
| [GetPublicKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md) | Gets the server's RSA public key, for encrypting secrets that a client sends to the server. | `session` `session` `idempotent` |
| [GetPublicKeyAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/index.md) | Gets the server's RSA public key without a session, for encrypting authentication data before login. | `session` `no session` |
| [GetRPCOverCOMInterface](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetRPCOverCOMInterface/index.md) | Gets RPC over COM interface for accessing M-Files Server. | `session` `no session` |
| [GetVaultConnectionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultConnectionInfo/index.md) | Gets the full connection information of the current vault session, in the form the M-Files COM API uses. | `session` `session` |
| [IsServerRunningInEvaluationMode](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/IsServerRunningInEvaluationMode/index.md) | Tells whether the server runs on an evaluation license, and how many evaluation days are left. | `session` `session` `idempotent` |
| [LoginForAutomaticUpdates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LoginForAutomaticUpdates/index.md) | Logs in for automatic updates. | `session` `no session` |
| [LogInRemote](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md) | Logs in (with authentication) to a remote server. | `session` `no session` |
| [Relogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/Relogin/index.md) | Logs in again by using the current session ID. Used by M-Files' own clients. | `session` `session` |
| [ResolveMaturityOfFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ResolveMaturityOfFeature/index.md) | Returns which of the named server feature flags are enabled on this server. | `session` `no session` |
| [SetOpenSessionCheck](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/SetOpenSessionCheck/index.md) | Sets whether administrators are warned about this session when they take the vault offline or do other maintenance. | `session` `session` |
| [VerifyLicenseSubscriptionTime](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime/index.md) | Fails if the server's license subscription has expired; succeeds otherwise. | `session` `no session` |