Connect Interface

The Connect Interface handles connections between users' accounts under different identity providers.

20 mins to read

Connect Interface

You can use the Connect Interface to let players sign in to your game through a supported identity provider. For more information about supported identity providers and configuration, see the Identity Provider Management documentation.

The Connect Interface:

Provides access to the Epic Online Services (EOS) Game Services.
Generates a common unique user identifier within the cross-platform services.
Links external identity providers' accounts to our services.

A player can associate one or more external user accounts with a unique player ID called a Product User ID (PUID). This Product User ID is a unique ID for each Product under the same Organization.

You can also use the Auth Interface to let players sign in to their Epic Games account directly from your game. See the Auth Interface documentation for more information on using the Auth Interface. The differences between the Auth Interface and Connect Interface are listed in the table below:

	Auth Interface	Connect Interface
Player ID	The player's Epic Games account ID. The player can sign in with an email and password combination, or a linked external account¹.	A Product User ID (PUID) for a player, that's linked to one or more supported identity providers². Note that the PUID is specific to a single product.
Access	The player can sign in to Epic Account Services across any platform (PC (Windows, Mac, and Linux), console, and mobile) and storefront.	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 Services	The player has access to the Friends³, Presence⁴, and Ecom⁵ interfaces, as well as the EOS Social Overlay⁶.	The player has access to Game Services across Multiplayer, Progression, Moderation, and Operations.
Access Token Lifetime	The game automatically refreshes the token as long as it calls `EOS_Platform_Tick`⁷.	The game must periodically refresh the player's token based on expiration notification events⁸.

Managing users

Users login using a set of external credentials. If the user already exists for this product, an access token is granted that lasts for a set period of time (currently one hour). The game is notified prior to the token expiration and is required to refresh the existing token, given a valid external credential at that time.

Epic Online Services interfaces cannot control the access permissions of the external provider. As such, Connect Interface

DOES:

Verify the user is still valid with the external account provider
Extend the time the user is able to access our services

DOES NOT:

Implicitly refresh tokens
Grant lengthy access

The external account provider is expected to have authoritative access to the application.

Access to services available via this user identifier requires external account identification via the EOS_ProductUserId data structure. All interfaces clearly indicate this usage and type safety should be assured. It is separate from EOS_EpicAccountId that is associated with the authentication interface provided for Epic Account Services.

Epic Games accounts are not required for using the Connect Interface that can be used with any of the supported external account types.

Authenticating Users

To authenticate with EOS Connect, follow these steps:

Call EOS_Connect_Login with the EOS_Connect_LoginOptions containing external credentials from a supported platform. You can sign in with any supported identity provider (for example, Steam, Xbox, or Nintendo). See the Identity Provider Management documentation for a complete list of supported identity providers. For instance, to authenticate with an Epic Games account, retrieve an ID token for the local Epic user from EOS_Auth_CopyIdToken and set the EOS_EExternalCredentialType to EOS_ECT_EPIC_ID_TOKEN.
Pass the EOS_HConnect handle, your EOS_Connect_LoginOptions structure, and your callback information to EOS_Connect_Login.

After authenticating, these additional actions may occur:

Provided that the EOS_HPlatform handle is ticking, the callback you provide executes when the operation finishes.
After a successful result, the application may access additional interfaces that require authentication.
If the user does not exist, the login API returns a EOS_InvalidUser result along with a EOS_ContinuanceToken. The token provides details about the login attempt and is required during the next steps in the login flow.

If your game supports cross-platform progression, when the player logs in the first time ask them if they have already previously played the game on another platform. If so, the player can authenticate using that platform’s external account to connect with their existing game progression, and then link that current platform account to their existing EOS user (see Linking an Account). Otherwise, you can ask if they want a fresh start by creating a new EOS user (see Creating a User).

User authentication refresh notification

A callback function provided to EOS_Connect_AddNotifyAuthExpiration will run whenever an existing access token is about to expire. This should give the application enough time to acquire another external access token and provide it to the SDK via the EOS_Connect_Login function each time.

Use the EOS_Connect_RemoveNotifyAuthExpiration function to stop listening for these notifications.

User authentication status change notification

To assure that your application knows whenever a user's authentication status has changed, the Connect Interface provides a callback for such notifications.

The callback function you provide to EOS_Connect_AddNotifyUserLoginStatusChanged runs whenever a local user's authentication status changes. This only occurs if the expiration notification is ignored, the external provider credentials are unable to refresh the access token, or the access was revoked explicitly by the backend service for some administrative reason. This callback fires only when other calls in the EOS ecosystem detect that this auth token is invalid; it does not automatically fire otherwise.

You must handle all the error messages in specific calls that may fail because of authentication. Recovery is often possible by calling EOS_Connect_Login then retrying the original call on success.

Use the EOS_Connect_RemoveNotifyUserLoginStatusChanged function to stop listening for notifications.

Checking current user authentication status

To check the player's current status on demand, use the EOS_Connect_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.

Creating a new user

Creating a user will generate a new Product User ID for the user given the external credentials used during login. It is almost always necessary to prompt the user and see if there is an alternate way to login before creating a new user. This will reduce confusion and user game progression merging issues in cross-platform situations.

If the application intends to create a new product user ID for the user, then simply call EOS_Connect_CreateUser with the EOS_Connect_CreateUserOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_CreateUserOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Linking an external account

If during the application login flow, it is determined that the user is able to login with a secondary set of external credentials, store the EOS_ContinuanceToken from the first login call, reattempt to login via EOS_Connect_Login, and once successfully logged in, immediately call EOS_Connect_LinkAccount. This will associate the two external accounts to the one product user ID. It is possible to link more than two accounts as the capabilities of our services grow.

If the intent of the application is to link a new external account with an existing product user ID, then call EOS_Connect_LinkAccount with the EOS_Connect_LinkAccountOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login and the product user ID for the user logged in with a successful call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_LinkAccountOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

You can search EOS Connect users by their external account IDs or using the product user ID through the Accounts dashboard in the Developer Portal. As the keychain of a player's linked external accounts is managed at the Organization level, the Accounts dashboard can be found next to the Organization management menu items. Through the Accounts dashboard, you will be able to find players and your customer support will be able to help to remove account linkings by player requests. You can also use this dashboard to remove your EOS Connect user or any linked accounts during SDK integration testing. Along with this, we will provide web REST APIs for developers to integrate EOS user management into their existing internal dashboards.

Unlinking an external account

During the first time user login flow, it is possible for the user to end up in a state where they inadvertently created a new product user ID for the logged in account (that is typically the local platform account), instead of reusing existing game progression that they may have from playing on another platform or using another external account credentials. The user may not be aware of the crossplay capabilities of the game.

In such a scenario, the user skips any early login dialogs and continues with their default platform account credentials (the logged in account) to create a new EOS_ProductUserId through the flow with EOS_Connect_Login and EOS_Connect_CreateUser APIs. As a consequence, their logged in account that is used with EOS_Connect_Login at game start is now tied with an unintended product user ID. To recover from this state, the user needs to be able to unlink the logged in account from the newly created keychain, so that they may enter the first time user login flow again.

Once they have unlinked the logged in account, they may login using another set of external account credentials linked with another existing keychain. On success, they then proceed to link the default logged in account with that desired existing keychain using the flow described in the Linking an External Account section above.

In another scenario, the user may simply want to disassociate the logged in account from its current keychain in order to separate game progressions between platforms or otherwise link it to another keychain.

To unlink an external account from a keychain that owns the product user ID currently logged in, call EOS_Connect_UnlinkAccount with the EOS_Connect_UnlinkAccountOptions, specifying LocalUserId as the EOS_ProductUserId that was returned by a previous call to EOS_Connect_Login. If the external account is not associated with any other product user IDs, the external account will be removed from the keychain. This means that the next attempt to login with EOS_Connect_Login using credentials associated with the same external account will return an EOS_InvalidUser result with an EOS_ContinuanceToken. If the external account is associated with other product user IDs, the operation removes the external account from the currently logged in product user ID but does not remove the external account from the keychain. This means that the external account is no longer returned in query APIs for the product, but the external account can still be used with the remaining product user IDs.

Similarly to the account linking creation operations, history of unlinking operations can be audited through the Accounts dashboard in the Developer Portal.

External account unlinking restrictions

In order to protect against account theft, unlinking accounts from a keychain is only possible for those accounts that the local user is currently logged in with. This prevents a malicious actor from gaining access to one of the linked accounts and using it to remove all other accounts linked with the keychain. It also prevents a malicious actor from replacing the unlinked account with their own corresponding account on the same platform, as the unlinking operation will ensure that any existing authentication session cannot be used to re-link and overwrite the entry without authenticating with one of the other linked accounts in the keychain.

These restrictions are in place to limit the potential attack surface related to account theft scenarios.

Using Device ID

This feature is relevant for Mobile personal devices and PC Desktop only. Device ID cannot be used with the Anti-Cheat Interfaces, which require an external account.

In cases where an application believes that users may not yet be invested enough to create a new account or link an existing account, an application may create a new persistent pseudo-account using the EOS Connect Device ID feature. This feature allows an application to create a persistent access credential for a local user without using any external login credentials. This allows the backend services to remember the current user on the local device across game sessions. The Device ID feature is used especially on mobile personal devices to allow automatically logging in a user without prompting for account credentials, as well as allowing to start playing the game without immediately requiring a user login to persist the game progression data.

However, as the Device ID is not tied to a real user account and can only be used to uniquely identify the local device, it is highly recommended to ask the user to link an external authentication method to their Device ID account once a user has progressed through some early progression milestone to prevent losing the credential and thus their account.

Without eventually linking the Device ID account with a real user identity, all progress and game data will be permanently lost should something happen to the device itself. The EOS SDK stores the Device ID credential locally in the keychain of the currently logged in user of the local device. If the local user profile is reset or otherwise lost, it is not possible to recover a lost Device ID after that.

To create a new Device ID, an application must call the EOS_Connect_CreateDeviceId function with a valid EOS_Connect_CreateDeviceIdOptions structure containing the user's DeviceModel. This call will eventually trigger a callback to the function bound to the EOS_Connect_OnCreateDeviceIdCallback. If a new Device ID was successfully created and stored in the keychain for the logged in user of the local device, the ResultCode parameter in the callback parameters will be set to EOS_EResult::EOS_Success. If an existing Device ID was already present, EOS_EResult::EOS_DuplicateNotAllowed is returned. Otherwise, the ResultCode parameter identifies the reason for the operation failure.

To login the local user with their unique Device ID, call the EOS_Connect_Login API with the EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN external credential type. As the SDK manages the stored Device ID credential automatically, the Token parameter of the input EOS_Connect_Credentials struct must be null. However, as the Device ID is not tied to a real user identity, the EOS_Connect_UserLoginInfo input struct needs to be provided with a valid DisplayName for the user.

To link the local Device ID with a real external user account, first have the game login the local user normally using the Device ID credential type. Then, ask the user to login with a real identity and after EOS_Connect_Login returns back with an EOS_ContinuanceToken, link the external account using the EOS_Connect_Link API to associate the local device with the user's real account. This will allow logging in the user automatically each time the game is started, as the Device ID can still be used as intended to automatically login the user without prompting for external user account credentials.

Deletion of Device ID credentials

You may also delete the Device ID for the current user profile of the local device by calling the EOS_Connect_DeleteDeviceId API. The deletion operation is a permanent and nonrecoverable operation. However, it is always possible to create a new Device ID and link it with an existing external user account to restore the automated login functionality.

On Android and iOS devices, uninstalling the application will automatically delete any local Device ID credentials created by the application.

On Desktop platforms (Linux, macOS, Windows), Device ID credentials are not automatically deleted. Applications may re-use existing Device ID credentials for the local OS user when the application is re-installed, or call the EOS_Connect_DeleteDeviceId API on the first run to ensure a fresh start for the user.

Linking Device ID based game progression with an existing linked accounts keychain

There is an edge-case scenario in which the common path to link a Device ID pseudo-account with a real external user account is not possible. In this scenario, the real user account that is logged in, already belongs to an existing keychain under the same EOS Organization. In such case, when the game first automatically logs in the user using the local Device ID login type and then the user logs in with real external user account credentials, the EOS_Connect_Login API will return an existing EOS_ProductUserId instead of an EOS_ContinuanceToken. To handle this specific scenario, the EOS_Connect_TransferDeviceIdAccount API is used.

The Device ID pseudo-account cannot be linked into the existing keychain, as the EOS_Connect_Link API requires the use of an EOS_ContinuanceToken. Additionally, as the player is now faced with two separate EOS_ProductUserIds, the player needs to be given a choice by the game on whether to discard one of the EOS_ProductUserIds (i.e. game profiles) as obsolete and continue to play with the other one. If the player chooses to discard one of the profiles, the game can link the local Device ID account into the existing keychain of linked accounts that is persistent on the backend.

To handle the scenario of two EOS_ProductUserIds, the game needs to recognize when it has logged in the local user using the Device ID login type and then the user, in the same game session, logs in using an external account and receives another EOS_ProductUserId session for it. When this happens, the game should attempt to automatically check whether one of the EOS_ProductUserIds does not have any meaningful game progression on the backend side. In this case, it should automatically discard it and link the local Device ID pseudo-account with the existing keychain of the real external user account.

In case the game is unable to determine this trivial case that can be automated on behalf of the user, it should prompt the user to make a choice on how to proceed. In this dialog, the player should be able to review the game progression as a comparison format for each EOS_ProductUserId and select which one to keep. It should be made very clear to the user that the discarded game progression will be lost forever and cannot be recovered afterwards. The game may also offer the user the option to not discard either profile, and to choose which one to continue playing with for the current game session.

If the user chooses to discard one of their game profiles and switch to another permanently, the game should call the EOS_Connect_TransferDeviceIdAccount API to transfer the local Device ID pseudo-account into the keychain that is linked with the real external user accounts. In the API, input struct EOS_Connect_TransferDeviceIdAccountOptions and set the ProductUserIdToPreserve parameter to point to the correct EOS_ProductUserId value to preserve in the Device ID transfer operation.

Retrieving Product User ID mappings

Other interfaces will expect the EOS_ProductUserId for remote or otherwise external users; say a list of friends or players on the same server. It is possible to convert external user account identifiers to the EOS_ProductUserId via the mapping API.

EOS_Connect_QueryExternalAccountMappings is an asynchronous call that will convert external account IDs to the SDK representation. Simply set the EOS_EExternalAccountType and provide a contiguous list of external account IDs in string form.

Pass the EOS_HConnect handle, your EOS_Connect_QueryExternalAccountMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via EOS_Connect_GetExternalAccountMapping. This function takes the EOS_EExternalAccountType as before and returns a single EOS_ProductUserId for each call that provides an external account ID in string form.

A common use case is to query other users who are connected through the same account system as the player (e.g. a player on Steam that queries another player on Steam for matchmaking). Queries using external account IDs of another account system are never available. For example, someone playing on Xbox can't access another player's Steam ID.

Retrieving external account mappings

Just as one may retrieve the product user ID for an external account, you can also retrieve the external accounts for a product user ID.

EOS_Connect_QueryProductUserIdMappings is an asynchronous call that will convert EOS_ProductUserIds to their external counterpart on a given platform, along with additional account data including the display name and the last login time. Simply provide a contiguous list of product user IDs.

Pass the EOS_HConnect handle, your EOS_Connect_QueryProductUserIdMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via

EOS_Connect_GetProductUserIdMapping. This function takes the EOS_EExternalAccountType, an input buffer, and buffer length to fill with the external account ID. If the buffer is too small, the proper size of the buffer will be returned.

Use EOS_Connect_GetProductUserExternalAccountCount to retrieve the number of linked external accounts for a product user.

Use EOS_Connect_CopyProductUserExternalAccountByIndex to fetch information about an external account linked to a product user using the index.

Use EOS_Connect_CopyProductUserExternalAccountByAccountType to fetch information about an external account of a specific type linked to a product user.

Use EOS_Connect_CopyProductUserExternalAccountByAccountId to fetch information about an external account linked to a product user using the account ID.

Use EOS_Connect_CopyProductUserInfo to fetch information about a product user, using the external account that they most recently logged in with as the reference.

If the product user ID does not map to the given external platform, then the data will not be present in the results returned for the above. This means that the user has never connected that external account type to their product user ID.

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 the product user 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.

The ID token returned by your OpenId provider must have the kid parameter value set in its header.

Retrieving an ID Token for user

Game clients can obtain ID Tokens for local users by calling the EOS_Connect_CopyIdToken SDK API after the user has been authenticated with EOS Connect, passing in a EOS_Connect_CopyIdTokenOptions structure containing the EOS_ProductUserId of the user.

The outputted EOS_Connect_IdToken structure contains the EOS_ProductUserId of the user, and a JWT representing the ID Token data. Note, you must call EOS_Connect_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. A new ID Token is provided after each successful EOS_Connect_Login call.

The ID Token is valid for the lifetime of the local user's EOS Connect authentication session. When the game client refreshes the authentication session, it should expect any earlier used ID Token to expire soon after, and a new ID Token to be used if needed.

Validating ID Tokens on game server using SDK

The JSON Web Key Set (JWKS) endpoint for EOS Connect ID Tokens is: https://api.epicgames.dev/auth/v1/oauth/jwks.

Game servers can validate ID Tokens by calling the EOS_Connect_VerifyIdToken SDK API, and passing in a EOS_Connect_VerifyIdTokenOptions containing the EOS_Connect_IdToken. Note, game servers should use EOS_ProductUserId_FromString to populate the EOS_ProductUserId part of the EOS_Connect_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:

Verify that the token signature algorithm ("alg") is present and is not set to "none".
Verify the JWT signature against the expected public certificate using the JWKS endpoint hosted by Epic Online Services.
Verify that the token issuer ("iss") is present and starts with the base URL of https://api.epicgames.dev.
Verify that the token issue time ("iat") is in the past.
Verify that the token expiration time ("exp") is in the future.
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 EOS Connect.

After successfully verifying the ID Token you can trust the Product User ID ("sub") value.

ID Token structure

The ID Token contains the following JSON structures:

Header

Key	Type	Description
alg	string	Signature algorithm.
kid	string	This is required. Identifier for the key that was used to sign the token.

Payload

Key	Type	Description
aud	string	Client ID used to authenticate the user with EOS Connect.
exp	integer	Expiration time of the token, seconds since the epoch.
iat	integer	Issue time of the token, seconds since the epoc.
iss	string	Token issuer. Always starts with `https://api.epicgames.dev`.
pfdid	string	EOS Deployment ID.
pfpid	string	EOS Product ID.
pfsid	string	EOS Sandbox ID.
sub	string	Product User ID of the authenticated user.
act	json object	Identifies the external account that was used to authenticate the connected user.

External account information (`act`)

Key	Type	Description
eat	string	Identifies the external account type. Possible values include: `apple`, `discord`, `epicgames`, `gog`, `google`, `itchio`, `nintendo_id`, `nintendo_nsa_id`, `oculus`, `openid`, `psn`, `steam`, `xbl`
eaid	string	External account ID.
pltfm	string	Platform that the user is connected from. Possible values include: `other`, `playstation`, `steam`, `switch`, `xbox`
dty	string	Device Type. Identifies the device that the user is connected from. Can be used to securely verify that the user is connected through a real Console device. Possible values include: `PSVITA`, `PS3`, `PS4`, `PS5`, `Switch`, `Xbox360`, `XboxOne`

Footnotes

See the Auth Interface documentation for more information on linked external accounts. ↩
See the Identity Provider Management documentation for more information on identity providers. ↩
See the Friends Interface documentation for more information on using the Friends Interface. ↩
See the Presence Interface documentation for more information on using the Presence Interface. ↩
See the Ecom Interface documentation for more information on using the Ecom Interface. ↩
See the Social Overlay Overview documentation for more information on the EOS social overlay. ↩
See the Api Reference documentation for more information on calling EOS_Platform_Tick. ↩
See the Connect Interface documentation for more information on expiration notification events. ↩

Connect Interface

The Connect Interface handles connections between users' accounts under different identity providers.