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.
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.
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.
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:
|Id||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.|
|Token||The user's login credentials or authentication token.|
|Type||The type of credential that this login attempt is using. EOS_ELoginCredentialType lists the available kinds of credentials.|
|SystemAuthCredentialsOptions||This field is for system specific options, if any are needed.|
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:
|Console||Platform access token used to automatically login the platform user to their associated Epic account.|
|Steam Client||Steam Session Ticket used to automatically login the local Steam user to their associated Epic account.|
|Epic Games Launcher||Exchange code received from the launcher and used to automatically login the user.|
|Other store platforms and standalone distributions on PC and Mobile Devices||Users 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.|
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