Auth Interface

Interface to handle verification of user accounts, including login and logout functionality.

To authenticate your Account Services Web APIs, use the Auth Web API.

Connecting to game sessions and interacting with other players over the Internet requires logging in to an account registered with Epic Online Services (EOS). It is fundamental that a user must be authenticated with the service before gaining permission to any of the additional services provided. The Auth Interface handles account-related interactions with EOS, providing the ability to authenticate users and obtain access tokens.


To use the Auth Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Basic Profile data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and user consent, you will still be able to initialize the EOS SDK and the Auth Interface, but all Auth Interface function calls to the back-end service will fail.

Authentication Functions

To access authentication functions, you need an EOS_HAuth handle, which you can acquire by calling the Platform Interface function, EOS_Platform_GetAuthInterface. Auth Interface functions require this handle to access user information.

Logging In

To begin interacting with EOS's online features, you must first log in with a valid user account. To do this, call the EOS_Auth_Login function with an EOS_Auth_LoginOptions structure containing a local player's account credentials. Whether the login attempt succeeds or fails, your callback function, of type EOS_Auth_OnLoginCallback, will run upon completion.

The EOS_Auth_LoginOptions must be initialized with its ApiVersion variable set to EOS_AUTH_LOGIN_API_LATEST, and its Credentials variable (of type EOS_Auth_Credentials) containing the following information:






The identity of the user logging in. Unlike most other functions, this should be a user-readable identity, like an email address or display name.


The user's login credentials or authentication token.


The type of credential that this login attempt is using. EOS_ELoginCredentialType lists the available kinds of credentials.


This field is for system specific options, if any are needed.


If Type is set to EOS_LCT_ExternalAuth, this field indicates which external authentication method to use. See EOS_EExternalCredentialType for a list of all available methods.

Pass the Auth Interface handle, your EOS_Auth_LoginOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.

Preferred Login Types for Epic Account

As of EOS SDK version 1.5, the preferred login types by platform are as follows:

Platform Type

Login Type


Epic Games Launcher


Exchange code received from the launcher and used to automatically login the user.



Platform access token used to automatically login the platform user to their associated Epic account.

PC or Mobile Device

EOS_LCT_AccountPortal with EOS_LCT_PersistentAuth

Web login flow with a locally stored long-lived access token.

For more detail on each platform type's preferred method, see the subsections below.


Your game retrieves an access token from the platform for the local user account. Using the EOS_LCT_ExternalAuth login type, the platform user is logged into their Epic account. See External Account Authentication for the detailed login flow, and the console specific documentation for the platform code integration.

PC or Mobile Device

PCs and mobile devices usually use persistent logins, enabled by long-lived refresh tokens granted by the authentication backend, and specific to the device and user account. On these platforms, the SDK automatically stores and retrieves these tokens as needed, and updates them following each login. See the section on persistent logins for more information.

Epic Games Launcher

When an application associated with the Epic Games Launcher starts, the launcher will provide a command line with several parameters, which will take this format:


The important fields of this command line are as follows:




This field may be the user ID, but it is presently unused.


This field will be the Exchange Code itself, which should be provided as the Token during login.


The type will read exchangecode, indicating that EOS_Auth_Login credentials should use the type EOS_LCT_ExchangeCode.

The application must parse this information and pass it into EOS_Auth_Login through the EOS_Auth_Credentials structure. EOS_Auth_Credentials has three variables: Id, Token, and Type. You may leave Id blank, as this login method does not require an ID. For Token, provide the Exchange Code from the AUTH_PASSWORD command line parameter. Finally, Type should be EOS_LCT_ExchangeCode.

Auth Scopes

As of EOS SDK version 1.5, EOS_Auth_LoginOptions contains a new field named ScopeFlags, of type EOS_EAuthScopeFlags. Scopes are a set of permissions that are required for your application to function properly. For example, if your application needs to see the user's friends list, then you must request the EOS_AS_FriendsList scope, and the user will be asked to give consent for it during the login flow. If the user does not consent to one of the requested scopes, then the login will fail. When requesting consent, your request must exactly match the scopes configured for the product in the Developer Portal.

Multiple users can be logged in at the same time on a single local device and using the same shared EOS_HPlatform instance

Persisting User Login to Epic Account Outside the Epic Games Launcher

On PC and mobile platforms, to support persistent user login outside of the Epic Games Launcher, use the EOS_LCT_AccountPortal login type.

The SDK automatically receives a refresh token from the authentication backend after a successful login to the user's Epic Account and stores the refresh token in the local keychain of the locally logged-in user on the device. For the local keychain, the SDK uses the secure credentials store provided by the device's operating system.

When automatically logging in the local user, the game should first call EOS_Auth_Login with the EOS_LCT_PersistentAuth login type. The Id and Token input fields should be set to NULL since the SDK manages the long-lived access credentials. The SDK will check for a refresh token in the keychain of the local user, and will automatically use a token, if it finds one, to log the user into their Epic Account. Following a successful login on those platforms, the SDK will automatically update the refresh token in the local keychain.

If EOS_Auth_Login fails for any reason, proceed with the default login method for the platform. If EOS_Auth_Login found a refresh token but failed to log in because the server rejected the token â€" meaning the call failed for a reason other than not having a token, connection or service issues, or the operation canceling or waiting to retry â€" the application should delete the token, since it is obsolete and will continue to cause failures in all future sessions. Call EOS_Auth_DeletePersistentAuth to explicitly remove any stored credentials in the local keychain for the user. The application should then proceed to the platform's default login flow.

In the case that a logged-in user wants to disable automatic login, call EOS_Auth_Logout to log out, and EOS_Auth_DeletePersistentAuth to revoke the user's long-lived logon session on the authentication backend. This will also delete the long-lived refresh token from the keychain of the local user.

Logging Out

To log out, call the EOS_Auth_Logout function with an EOS_Auth_LogoutOptions data structure. When the operation completes, your callback function, of type EOS_Auth_OnLogoutCallback, will run. Initialize your EOS_Auth_LogoutOptions structure as follows:






The EOS_EpicAccountId

Pass the Auth Interface handle, your EOS_Auth_LogoutOptions structure, and your callback function to EOS_Auth_Logout. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.

If the EOS_LCT_PersistentAuth login type has been used, be sure to also call the function EOS_Auth_DeletePersistentAuth to revoke the long-lived logon session on the authentication backend. This will also permanently forget the local user login on the local device.

Status Change Notification

The EOS SDK periodically verifies local users' authentication status during the application's lifetime. This helps to make sure that the user hasn't signed in elsewhere or otherwise lost access for reasons external to the application itself. To assure that your application knows whenever a user's authentication status has changed, the Auth Interface invokes a callback of type EOS_Auth_OnLoginStatusChangedCallback upon any such change for any local player. You can attach your own callback function to this process with the EOS_Auth_AddNotifyLoginStatusChanged function.

The EOS_Auth_OnLoginStatusChangedCallback callback function you provide will run whenever a local user's authentication status changes. This includes explicitly logging in and out with the Auth Interface, meaning that you will receive both the callback for the log in (or log out) event as well as this callback.

Connectivity loss during an application's lifetime does not indicate that a user is logged out. The EOS backend will explicitly notify the Auth Interface when a logout event takes place, and this is the only case in which it is safe to assume that the user is officially considered offline. User connectivity problems such as service outages, or local hardware failure can cause various API features to fail. If the game can continue without these interactions, the recommended course of action is to continue playing with the assumption that connectivity may eventually resume without logging the user out.

Checking Current Authentication Status

To check the player's current status on demand, use the EOS_Auth_GetLoginStatus function. This function determines authentication status is determined based on the most recent communication with the online service, so the result is returned instantly, and does not use a callback function.

Verifying Authentication

In some cases, you may want to verify a remote user's identity, such as when a user attempts to join a dedicated server. Calling EOS_Auth_VerifyUserAuth with an EOS_Auth_VerifyUserAuthOptions structure will ask EOS to verify the user's authentication status, and run your callback function (of type EOS_Auth_OnVerifyUserAuthCallback, taking an EOS_Auth_VerifyUserAuthCallbackInfo parameter) upon completion. To initialize your EOS_Auth_VerifyUserAuthOptions structure, set the following values:






The authentication token (type EOS_Auth_Token) in use by the remote user.

Pass your Auth Interface handle, your EOS_Auth_VerifyUserAuthOptions data structure, and your callback information to the function. When the operation finishes, your callback will run, providing you with the result. If the result comes back negative, you should remove the user from the server, as it is likely that the user is attempting to spoof another. Local players do not need verification, as the SDK itself handles that.

External Account Authentication

To log in with EOS_Auth_Login using an external account, set Type in EOS_Auth_Credentials to EOS_LCT_ExternalAuth, set ExternalType to an external credential type (see EOS_EExternalCredentialType for a list of all available methods), and set Token to the external authentication token. For example, if you want to log in with Steam, you would use EOS_ECT_STEAM_APP_TICKET as the ExternalType, and the Token would be the Steam Encrypted Application Ticket.

EOS_InvalidUser will be returned when the external auth login fails due to an external account not being linked. An EOS_ContinuanceToken will be set in the EOS_Auth_LoginCallbackInfo data. EOS_Auth_LinkAccount should be called with the EOS_ContinuanceToken and LinkAccountFlags set to EOS_LA_NoFlags (for most cases where consent is required via the Account Portal or PIN Grant) to continue the external account login and link the external account. Afterwards, the external account will be linked to the user’s Epic Account.

The Identity Providers on the Developer Portal will need to be configured for your product to enable linking providers using external account authentication. See Configuring Identity Providers for more information.

EOS Auth flow

Integrating a Game Launcher With Epic Games Store

If your game provides a launcher to include additional launch options, promotions or other news, then your launcher must manage the login flow. Exchange codes generated by the Epic Games Launcher expire after a short period of time, so care must be taken to prevent the exchange code from expiring. Use the following pattern when the Epic Games Launcher is not directly launching the game application:

  1. The Epic Games Launcher starts the third-party launcher, passing the exchange code on the command line as described above in the section Associating With the Epic Games Launcher

  2. The third-party launcher uses the Exchange Code to login the player by using the EOS_Auth_Login API. Initialize EOS_Auth_LoginOptions by setting the Type and Token fields of the EOS_Auth_ClientCredentials struct to EOS_LCT_ExchangeCode and the exchange code from the command line respectively.

  3. When the player chooses to launch the game, use the EOS_Auth_CopyUserAuthToken API to get a copy of the token details. Copy the RefreshToken from the EOS_Auth_Token and call the EOS_Auth_Token_Release API to free the memory allocated by the SDK.

  4. Pass the refresh token to the game application by setting an environment variable that the game can read on startup. Do not log the player out in the third-party launcher when it exits as this will invalidate the refresh token.

  5. When the game process starts up, the game can log the player in using the EOS_Auth_Login API. Initialize EOS_Auth_LoginOptions by setting the Type and Token fields of the EOS_Auth_ClientCredentials struct to EOS_LCT_RefreshToken and the refresh token from the environment variable respectively.