Auth Interface

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

30 mins to read

Auth Interface

The Auth Interface lets players (users) log into their Epic Account from your game (product) so they can access the features provided by Epic Account Services (EAS), such as Friends, Presence, UserInfo and Ecom interfaces. The Auth Interface handles Epic account-related interactions with EOS, providing the ability to authenticate users and obtain access tokens.

If you have a userless client setup (i.e. your Client Policy doesn't require a user), you can initialize the client using just the client_credentials. You don't need any user information.

To use the Auth Interface, your game (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 EAS’s online features, players must first log in with a valid Epic Account. To set this up so that players can 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 brand review process verifies your game's brand with Epic Games. Once verified, players outside of your organization can use your game's integration of Epic Account Services. Prior to brand review, players receive an error if they try to log into your game with an external account. See the documentation on the Brand Review Application Process for more details.

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:

PropertyValue
ApiVersionEOS_AUTH_CREDENTIALS_API_LATEST
IdThe identity of the user logging in. Unlike most other functions, this should be a user-readable identity, like an email address or display name.
TokenThe user's login credentials or authentication token.
TypeThe type of credential that this login attempt is using. EOS_ELoginCredentialType lists the available kinds of credentials.
SystemAuthCredentialsOptionsThis field is for system specific options, if any are needed.
ExternalTypeIf 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 SDK 1.5 version, the preferred login types by platform are as follows:

PlatformLogin TypeSummary
ConsoleEOS_LCT_ExternalAuthPlatform access token used to automatically login the platform user to their associated Epic account.
Steam ClientEOS_LCT_ExternalAuthSteam Session Ticket used to automatically login the local Steam user to their associated Epic account.
Epic Games LauncherEOS_LCT_ExchangeCodeExchange code received from the launcher and used to automatically login the user.
Other store platforms and standalone distributions on PC and Mobile DevicesEOS_LCT_AccountPortal with EOS_LCT_PersistentAuthUsers are prompted to login using their Epic account credentials, after which a long-lived refresh token is stored locally to enable automatic login across consecutive application runs.
Console

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:

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal -epicusername=<username> -epicuserid=<userid> -epiclocale=en-US