Auth Interface

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

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:

Property

Value

ApiVersion

EOS_AUTH_CREDENTIALS_API_LATEST

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.

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 are as follows:

Platform

Login Type

Summary

Console

EOS_LCT_DeviceCode with EOS_LCT_PersistentAuth

PIN code to authorize the local device to receive and store a long-lived access token locally.

Mobile

EOS_LCT_AccountPortal with EOS_LCT_PersistentAuth

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

Desktop PC

EOS_LCT_AccountPortal with EOS_LCT_PersistentAuth

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

Epic Games Launcher

EOS_LCT_ExchangeCode

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

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, a 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.

Additionally for the Console login flow, as of 1.5, a new field named VerificationURIComplete can be used to directly continue the login flow. 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.

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. You may request consent for any and all scopes, but it is best practice to only request the ones your application actually needs.

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

Associating With the 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:

Property

Value

AUTH_LOGIN

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

AUTH_PASSWORD

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

AUTH_TYPE

The type will read "exchangecode", indicating that EOS_Auth_LoginCredentials should use the type EOS_LCT_ExchangeCode.

This information must be parsed by the application and provided to the EOS_Auth_Login through the EOS_Auth_Credentials structure. EOS_Auth_Credentials has three variables: Id, Token, and Type. For the Type, use EOS_LCT_ExchangeCode. You may leave Id blank, as this field is unused for this login type. Finally, provide the Exchange Code from AUTH_PASSWORD as the Token.

Persisting User Login to Epic Account Outside the Epic Games Launcher

On PC Desktop and Mobile devices the user is logged in using the EOS_LCT_AccountPortal login type. For these platforms, the SDK will internally automatically store a long-lived refresh token that is received from the authentication backend on a successful login to the user's Epic Account. The long-lived refresh token is stored 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 operating system of the device.

On Console, similarly to PC Desktop and Mobile, the SDK will receive a long-lived refresh token that can be used to automatically login the local user on consecutive game sessions. However, in order to do so, the calling application needs to use the EOS_Auth_CopyUserAuthToken API 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 that the refresh_token is stored per-user 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 be able to login to the Epic account belonging to another user of the device.

For automatically logging in the local user, the game should always first call the EOS_Auth_Login API using the EOS_LCT_PersistentAuth login type.

On PC Desktop and Mobile, as the SDK manages the long-lived access credentials the Id and Token input fields should be set to NULL. The SDK will check for any previously stored refresh token in the keychain of the local user, and if found automatically use it to login the user to their Epic Account. On a successful login the SDK will update the refresh token in the local keychain automatically.

On Console, the Id should be NULL and the Token point to a previously stored long-lived refresh token string. On a successful login the application should use the EOS_Auth_CopyUserAuthToken API to retrieve a renewed copy of the refresh_token and update the locally stored token with the renewed version.

If no refresh token was found, the EOS_Auth_Login API will return the EOS_EResult::EOS_NotFound error result. If an error is encountered and depending on the error, the caller should use the EOS_Auth_DeletePersistentAuth API to explicitly remove any stored credentials in the local keychain for the user (PC Desktop and Mobile). Below is a table describing the error results that when encountered the caller should not call the EOS_Auth_DeletePersistent API.

EOS_EResult

Description

EOS_Canceled

The login operation was cancelled from the outside.

EOS_OperationWillRetry

An error occurred during an asynchronous operation and it will be retried.

EOS_AlreadyPending

There is an asynchronous request pending already for the login operation.

EOS_TooManyRequests

The login request was throttled due to too many requests being sent by the client.

EOS_TimedOut

The login request to the backend timed out.

EOS_ServiceFailure

The authentication backend server could not be reached.

EOS_NotFound

No persistent access credentials were found in the local keychain store.

In all other error cases, the caller must always call the EOS_Auth_DeletePersistentAuth API. This is important to ensure that the game will not attempt to login using expired, invalid or otherwise bad access credentials when the game is next time started.

As such, when launching the application outside the Epic Games Launcher, the user login flow is implemented as follows:

  1. Attempt to login the user automatically with EOS_Auth_Login using the EOS_LCT_PersistentAuth login type.

    • If the API returns a success, the user has been successfully logged in.

    • If the API fails and returns any other error result than one listed in the table above, call EOS_Auth_DeletePersistentAuth and delete the locally stored long-lived refresh token.

  2. If the login failed, take the user to the default login flow for the platform.

If the user wants to be forgotten and no longer automatically logged in, call EOS_Auth_Logout and then use the EOS_Auth_DeletePersistentAuth API to revoke the user's long-lived logon session on the authentication backend and to delete any existing persistent access credentials stored in 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:

Property

Value

ApiVersion

EOS_AUTH_LOGOUT_API_LATEST

LocalUserId

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

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:

Property

Value

ApiVersion

EOS_AUTH_VERIFYUSERAUTH_API_LATEST

AuthToken

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.