Auth Interface

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.

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:

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:

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

Console

On Console, when using the EOS_LCT_DeviceCode login type, an additional callback is made by the EOS_Auth_Login API at the beginning of the login flow. Within this first intermediate callback, an EOS_Auth_PinGrantInfo data structure is returned to the caller, containing the PIN code (UserCode) and the website URI that the application needs to present to the user. This will allow the user to complete the login flow using a separate device, such as a mobile phone or PC. In versions 1.5 and higher, there is a new field named VerificationURIComplete that you can use to continue the login flow directly. For example, it can be used in a button or hyperlink, or it can be rendered as a QR code to be scanned by a mobile phone.

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. This method is also available on consoles, though the application must manage refresh token storage on a per-user basis to prevent local users from logging into each other's accounts. 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

The important fields of this command line are as follows:

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_EAuthScopeFlagsEOS_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.

Persisting User Login to Epic Account Outside the Epic Games Launcher

To support persistent user login outside of the Epic Games Launcher, use the EOS_LCT_AccountPortal login type. You will need a long-lived refresh token from the authentication backend to use this method.

The SDK automatically receives a refresh token from the authentication backend after a successful login to the user's Epic Account. On PC and mobile platforms, the SDK automatically stores the 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. On consoles, you will need to call EOS_Auth_CopyUserAuthToken to retrieve the received refresh_token value and store it for the currently logged in device user locally on the local device. It is important to store the refresh_token on per-user basis, and specifically for the currently logged-in user of the device, so that if another user on a shared device runs the application, they will not have access to the refresh token.

When automatically logging in the local user, the game should first call EOS_Auth_Login with the EOS_LCT_PersistentAuth login type. On PCs and mobile devices, 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. On consoles, the Id field should be NULL, but the Token field should point to the refresh token string from a previous login. Following a successful console login, the application should call EOS_Auth_CopyUserAuthToken to retrieve an updated refresh token and overwrite the previous one in the console's storage device. As with the original refresh token, this must be done in user-specific storage in order to prevent other local users from logging in with the wrong Epic Account.

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. On PCs and mobile devices, call EOS_Auth_DeletePersistentAuth to explicitly remove any stored credentials in the local keychain for the user. On consoles, delete the stored token from local storage. 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. On PCs and mobile platforms, this will also delete the long-lived refresh token from the keychain of the local user. On consoles, the application must remove the stored token from local storage.

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:

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. On PC Desktop and Mobile, 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.

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:

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, 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 Encrypted Steam App Ticket.

If an external account is not linked when the user begins the authentication flow, the Account Portal will enable authentication to continue once a user has logged in. Afterwards, the external account will be linked to the user's Epic Account.

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

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.