Auth Interface

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

30 mins to read

Note: You can also authenticate with the Auth Web APIs. See EOS Web API References: Auth Web API documentation for more information.

Auth Interface

You can use the Auth Interface to let players sign in to their Epic Games account directly from your game. Use the interface to authenticate players, get access tokens, and handle other account-related interactions with Epic Online Services. When a player signs in to their Epic Games account, you can give them access to other Epic Account Services such as Friends, Presence, User Info and Ecom Interfaces.

You can also use the Connect Interface to let players sign in to your game through a supported identity provider. See the Connect Interface documentation for more information on using the Connect Interface in your game. The differences between the Auth Interface and Connect Interface are listed in the table below:

Auth InterfaceConnect Interface
Player IDThe player's Epic Games account ID. The player can sign in with an email and password combination, or a linked external account1.A Product User ID (PUID) for a player, that's linked to one or more supported identity providers2. Note that the PUID is specific to a single product.
AccessThe player can sign in to Epic Account Services across any PC (Windows, Mac, and Linux) platform and storefront. Note: Game console and mobile platform access is coming at a future date.The player can authenticate their account in your game to access EOS Game Services across any platform (PC (Windows, Mac, and Linux), console, and mobile) and storefront.
Supported ServicesThe player has access to the Friends3, Presence4, and Ecom5 interfaces, as well as the EOS Social Overlay6.The player has access to Game Services across Multiplayer, Progression, Moderation, and Operations.
Access Token LifetimeThe game automatically refreshes the token as long as it calls EOS_Platform_Tick7.The game must periodically refresh the player's token based on expiration notification events8.

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.

Note: To use Epic Online Services (EOS) SDK, your local network, router, and firewall must allow access to specific host addresses. For a complete list of these host addresses, see the Firewall Considerations documentation.

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

The preferred login types by platform are as follows:

PlatformLogin TypeSummary
Epic Games LauncherEOS_LCT_ExchangeCodeExchange code received from the launcher and used to automatically login the user.
Nintendo SwitchEOS_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.
PlayStation and XboxEOS_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 Steam user to their associated Epic account.
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.
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:

PropertyValue
AUTH_LOGINThis field may be the user ID, but it is presently unused.
AUTH_PASSWORDThis field will be the Exchange Code itself, which should be provided as the Token during login.
AUTH_TYPEThe type will read "exchangecode", indicating that EOS_Auth_LoginCredentials 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.

Nintendo Switch

Your game stores a long-lived Epic refresh token on the local device for automatic login across game sessions. See the section on persistent logins for more information.

PlayStation, Steam, and Xbox

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.

You can only access console documentation if you have the appropriate permissions. See the Get Started Steps: EOS SDK Download Types documentation for more information on how to access the EOS SDKs for consoles and their associated documentation.

PC and Mobile Devices

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.

Auth Scopes

As of EOS SDK version 1.5, EOS_Auth_LoginOptions contains a new field named ScopeFlags, of type EOS_EAuthScopeFlags (API LINK). 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

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:

The important fields of this command line are as follows: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 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:

PropertyValue
ApiVersionEOS_AUTH_LOGOUT_API_LATEST
LocalUserIdThe 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.

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 based on the most recent communication with the online service, so the result is returned instantly, and does not use a callback function.

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_SESSION_TICKET as the ExternalType, and the Token would be the Steam Session 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 the Product to allow providers to be linked using external account authentication. See Configuring Identity Providers for more information.

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

User Verification Using an ID Token

ID Tokens are part of the OpenID Connect protocol and can be used to verify a user's identity on server-side. An ID Token is a JSON Web Token (JWT) that contains information about the authenticated user, such as their account id. This allows backend services and game servers to securely verify user identifiers it receives from clients.

ID Tokens can not be used to execute actions on behalf of a user. They are only intended for the use of user identity verification.

Retrieving an ID Token For User

Game clients can obtain ID Tokens for local users by calling the EOS_Auth_CopyIdToken SDK API after the user has been logged in, passing in a EOS_Auth_CopyIdTokenOptions structure containing the EOS_EpicAccountId of the user.

The outputted EOS_Auth_IdToken structure contains the EOS_EpicAccountId of the user, and a JWT representing the ID Token data. Note, you must call EOS_Auth_IdToken_Release to release the ID Token structure when you are done with it.

Once retrieved, the game client can then provide the ID Token to another party. An ID Token is always readily available for a logged in local user.

Validating ID Tokens on Game Server Using SDK

The JSON Web Key Set (JWKS) endpoint for EOS Auth ID Tokens is: https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json.

Game servers can validate ID Tokens by calling the EOS_Auth_VerifyIdToken SDK API, and passing in a EOS_Auth_VerifyIdTokenOptions containing the EOS_Auth_IdToken. Note, game servers should use EOS_EpicAccountId_FromString to populate the EOS_EpicAccountId part of the EOS_Auth_IdToken structure before calling verify, because the server's user handles will be different to the user handles on the client.

Validating ID Tokens on Backend Without SDK

Backend services can verify the validity of ID Tokens and extract the token claims using any of the publicly available standard JWT libraries. See https://jwt.io/ for a list of libraries for this purpose. The used library should allow automatic caching of the retrieved JWKS information for the best performance and to reduce networking overhead.

The EOS SDK and other support libraries take care of the needed steps for securely validating the ID Token before its containing claims can be securely trusted. The steps performed are as following:

  1. Verify that the token signature algorithm ("alg") is present and is not set to "none".
  2. Verify the JWT signature against the expected public certificate using the JWKS endpoint hosted by Epic Online Services.
  3. Verify that the token issuer ("iss") is present and starts with the base URL of https://api.epicgames.dev.
  4. Verify that the token issue time ("iat") is in the past.
  5. Verify that the token expiration time ("exp") is in the future.
  6. Verify that the Client ID ("aud") matches the Client ID that you are using to initialize the EOS SDK with game clients or otherwise to authenticate users with Epic Account Services.

After successfully verifying the ID Token you can trust the Epic Account ID ("sub") value.

ID Token Structure

The ID Token contains the following JSON structures:

Header

KeyTypeDescription
algstringSignature algorithm.
kidstringIdentifier for the key that was used to sign the token.
tstringToken type. Always set to id_token.

Payload

KeyTypeDescription
appidstringEAS Application ID.
audstringClient ID used to authenticate the user with Epic Account Services.
ctystringCountry code that the Epic Account has been registered with, in ISO 3166 2-letter format. This optional claim will be present if the application has requested the country scope.
dnstringEpic Account display name.
expintegerExpiration time of the token, seconds since the epoch.
iatintegerIssue time of the token, seconds since the epoch.
issstringToken issuer. Always starts with https://api.epicgames.dev.
pfdidstringEOS Deployment ID.
pfpidstringEOS Product ID.
pfsidstringEOS Sandbox ID.
substringEpic Account ID of the authenticated user.
eatstringExternal acccount type. This optional claim will be present if the user has logged in to their Epic Account using external account credentials, e.g. through local platform authentication.
eadnstringExternal account display name. This claim might not be always present.
pltfmstringPlatform that the user is connected from. Included if the eat claim is present. Possible values include:
  • other
  • playstation
  • steam
  • switch
  • xbox

Footnotes

  1. See the Auth Interface documentation for more information on linked external accounts.

  2. See the Identity Provider Management documentation for more information on identity providers.

  3. See the Friends Interface documentation for more information on using the Friends Interface.

  4. See the Presence Interface documentation for more information on using the Presence Interface.

  5. See the Ecom Interface documentation for more information on using the Ecom Interface.

  6. See the Social Overlay Overview documentation for more information on the EOS social overlay.

  7. See the Api Reference documentation for more information on calling EOS_Platform_Tick.

  8. See the Connect Interface documentation for more information on expiration notification events.