Auth Interface

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

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:

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.

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.

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.

The preferred login types by platform are as follows:

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:

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.

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.

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.

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.

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.

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.

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.

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. This will also permanently forget the local user login on the local device.

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.

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.

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.

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.

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.

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.

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.

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.

The ID Token contains the following JSON structures:

Header

Payload

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