Getting Started

How to set up EOS Epic Account Services with your product.

12 mins to read

EOS Epic Account Services is part of Epic Online Services (EOS). EOS consistes of two sets of resources: EOS Epic Game Services, and EOS Epic Account Services. See the following documentation to find out more: Epic Online Services (EOS) Overview and EOS Quick Start

EOS Epic Account Services are a set of resources which are specific to using Epic Games accounts in your game.

If you use EOS Game Services in your game, you do not require EOS Epic Account Services. Players can connect to your game using either an identity from a supported identity provider (such as a Steam account) or an Epic Games account.

Tip

  • A player connecting via an identity from a supported identity provider (such as a Steam account) uses:
    • EOS Game Services: Connect Interface.
  • A player connecting via an Epic Games account uses both:
    • EOS Game Services: Connect Interface, and
    • EOS Epic Account Services: Auth Interface.

For more information, see the following documentation:

Before you start

Before you can begin setting up an EOS Epic Account Services account and application, be sure that you fulfill these prerequisites:

  1. Sign up for the Developer Portal (dev.epicgames.com/portal) and enable multi-factor authentication on your account.
  2. In the Developer Portal, create your own organization or become a member of an existing one.
    To do this, you need an Epic Games account (see www.epicgames.com/account) and your organization memberhsip role needs to be Admin.
  3. Create or pick a product to use EOS Epic Account Services.
  4. From the Developer Portal, download the latest version of EOS SDK.
    See the EOS Quick Start for more information on the EOS SDK.

Get started

1. Accessing EOS Epic Account Services in the Developer Portal

You can find Epic Account Services from the Developer Portal along the navigation panel or the home page for a product.

To proceed to the Epic Account Services dashboard, you must review and accept a Service Addendum for Epic Account Services. You can always review all accepted agreements under the Licenses tab of the Organization section in the Developer Portal.

You should also review the Epic Games Privacy Policy to understand how Epic Games collects, uses, and shares user data.

Depending on your organization type, you may only need to accept each license agreement once (as a Company entity). However, Individual entities require each member with access to the EAS dashboard to accept the agreement.

With EOS Game Services, you license Epic Games as a service provider to process the data of your users on your behalf. But with EOS Epic Account Services, Epic Games manages the player data and authentication flows to expose this data and functionality on your players' behalf, with their consent. From your end, you agree to use the data for permitted uses only, as defined in the Service Addendum for Epic Account Services.

2. Setting Up an EOS Epic Account Services Application

From the Epic Account Services dashboard, you can proceed creating your first application. The Developer Portal will show a placeholder for a future application, but none of the configuration details.

EOS Epic Account Services Application on Dashboard

Click to enlarge image.

Application configuration consists of three major sections:

  1. Brand Settings: Name, logo, privacy policy URL, and support URL.
  2. Permissions: The access permissions that the application asks users for.
  3. Linked Clients: Association of the application with client credentials used by the SDK during the authentication flow.

Click Configure to proceed with each of these.

Application Brand Settings

The first section for configuring your application is Application Brand Settings.

Application Brand Settings

Click to enlarge image.

On the left you can see a preview of the consent dialog that will be shown to Epic users requesting their permission to share information with that application. The preview is available in a mobile and a web version.

Initially, a red warning banner will appear at the top of the preview for the consent dialog. This warning indicates that the application brand settings have not been reviewed against potential toxicity or an attempt to spoof the brand. Additionally, the consent dialog for an unverified application is prefaced with another warning dialog. The purpose of the double warning is to fully ensure that the user understands all the implications of proceeding with an unverified application.

All applications are created unverified, and with audience restrictions in place. Only members of the same development organization will be able to use their Epic Games accounts to authenticate against this unverified application. All other users will see an audience restriction error message. The purpose of these audience restrictions is to protect Epic users while allowing developers to iterate on integration while they prepare the application for the brand review.

To remove these restrictions, the details in the fields on the right must be filled out and submitted for Application Brand Review. These include:

  • Application Name: A friendly name for your application that will display to users. This is set to the product name by default.
  • Privacy Policy URL: A URL where users can find your application's privacy policy.
  • Application Logo: A 128 x 128 opaque PNG or JPG that will represent your application on the consent dialog.

As you update these fields, the preview will immediately update to reflect your changes.

Application Brand Settings after being filled

Click to enlarge image.

Once application is created and brand settings are saved, go to the next tab.

Application Permissions

The Permissions tab is where you define the level of access the application will request from the user.

Application Permissions

Click to enlarge image.

Epic Account Services ships with support for three basic permissions:

  • Basic Profile: Allows read access to user display name, language preferences and linked account display names.
  • Online Presence: Allows the application to set the online presence of the current user and receive online presence updates from their friends.
  • Friends: Allows read access to the friends list for the current user's account.

Basic Profile is always required for Epic Account Services and can not be deactivated as you cannot get access to any user data without it. Online Presence and Friends may be enabled or disabled per the needs of your application. Toggle on the permissions you want to enable for your application, then click Save to save your changes. The consent dialog preview will update to reflect the permissions you add or remove.

Application Permissions after being enabled

Click to enlarge image.

Application Clients

Finally, the Clients tab enables you to configure a list of clients associated with this application. A client is any piece of software or website that can access the application's data within the Epic Account Services backend. All clients associated with an application are listed in its Product Settings, and all of them share the user's consent once it is given.

Unconfigured application clients tab

Click to enlarge image.

If you already have clients set up for your application, you can select them from the Select Clients dropdown. Otherwise, click Create New Client to open your Product Settings page and configure a new client. For more information, refer to the Client Credentials page for more information on adding new clients.

Once you have added a client to this list, click the Save button to save your changes.

Dashboard with configured application

Click to enlarge image.

At this point you have completed the EOS Epic Account Services Application Configuration. From here you are ready to integrate EAS into a product and use it to access user data. Following a review of the application brand settings you submitted, audience restrictions will be lifted, and the application can be made visible to users outside of your organization.

Application Permissions after being enabled

Click to enlarge image.

3. Authenticating Epic Games Users with the EOS SDK

Using an Epic Games account requires no special setup with the EOS SDK. However, you must use a login type appropriate for your target platform (see the Auth Interface), and you must remember to include the scopes you want the user to consent to in the login call that you denoted during your brand review application (their profile, presence, and friends list).

For example, to login via the account portal on a PC, your login call may appear as follows:

EOS_Auth_Credentials Credentials = { 0 };
Credentials.ApiVersion = EOS_AUTH_CREDENTIALS_API_LATEST;
Credentials.Type = EOS_LCT_AccountPortal;
EOS_Auth_LoginOptions LoginOptions = { 0 };
LoginOptions.ApiVersion = EOS_AUTH_LOGIN_API_LATEST;
LoginOptions.ScopeFlags = EOS_AS_BasicProfile | EOS_AS_FriendsList | EOS_AS_Presence;
LoginOptions.Credentials = &Credentials;
EOS_Auth_Login(AuthHandle, &LoginOptions, NULL, OnLoginCallback);

This opens a default system web browser that prompts the user to login and review the access application requests.

4. Authenticating Epic Games Users on a Web Site

To authenticate your users on websites and web applications, we support the authorization code flow for OpenID Connect Core 1.0. But before you begin, you must configure an brand review application and client credentials.

User Authorization

To initiate the authentication flow, your application must redirect the user to the authorization page where they will login to their Epic Games account.

Redirect your users to this authorization URL:

https://www.epicgames.com/id/authorize?client_id={client_id}&response_type=code&scope=basic_profile&redirect_uri=https://www.example.com&state=rfGWJux2WL86Zxr6nKApCAnDo8KexEUE

To request additional permissions, modify the scope parameter in the authorization request with a space-delimited list of the required permissions. For example, scope=basic_profile friends_list.

You then need to configure the redirect URL for the Client in your Developer Portal.

When a user logs in, they are asked to approve the requested permissions. After accepting, they are redirected back to your application with a code parameter. This code is used when requesting an access token.

Epic Games also supports an optional state parameter that you can use to maintain state between the request and the callback. This can prevent cross-site request forgery attacks.

The following is an example redirect URL after a user is authenticated:

https://www.example.com/?code=cfd1de1a8d224203b0445fe977838d81&state=rfGWJux2WL86Zxr6nKApCAnDo8KexEUE

Requesting an Access Token

To request an access token, the client makes a request to the token endpoint, including the client credentials and authorization code. The Epic Games token endpoint is https://api.epicgames.dev/epic/oauth/v1/token.

The client credentials pass in the Authorization header using basic authorization.

In the request, you also need to specify the authorization_code grant type and include the code and redirect URL from the authorization flow.

The following snippet shows a sample request (using password grant type):

POST /epic/oauth/v1/token HTTP/1.1
Host: api.epicgames.dev
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Zm9vOmJhcg==
grant_type=authorization_code&
deployment_id=foo&
scope=basic_profile&
code=cfd1de1a8d224203b0445fe977838d81&
redirect_uri=https://www.example.com

The response contains the following fields:

ResponseDescription
access_tokenThe access token, which may optionally have a prefix (for example: eg1~token). This value should be passed as-is in the Authorization header using the Bearer type on any requests to Epic services.
expires_inThe number of seconds until the token expires.
expires_atThe expiration date in ISO 8601 format.
account_idThe Epic Games account ID for the user that the token was generated for.
client_idThe Client ID which was used to generate this token.
application_idThe Application ID which the Client is associated with.
token_typeThe type of token generated, value will always be bearer.
refresh_tokenThe refresh token will optionally be returned depending on the client configuration. This refresh token can be used to extend a session before or after the access token has expired.
refresh_expiresThe number of seconds until the refresh token expires.
refresh_expires_atThe refresh token expiration date in ISO 8601 format.

The following snippet shows a sample response:

{
"scope": "basic_profile",
"token_type": "bearer",
"access_token": "eyJ0IjoiZXBpY19pZCIsImFsZyI6IlJTMjU2Iiwia2lkIjoibldVQzlxSFVldWRHcnBXb3FvVXVHZkFIYmVWM2NsRnlsdFRYMzhFbXJKSSJ9.eyJhdWQiOiJ4eXphNzg5MWxoeE1WWUdDT043TGduS1paOEhRR0Q1SCIsInN1YiI6Ijk2MjZmNDQxMDU1MzQ5Y2U4Y2I3ZDdkNWE0ODNlYWEyIiwidCI6ImVwaWNfaWQiLCJzY29wZSI6ImJhc2ljX3Byb2ZpbGUgZnJpZW5kc19saXN0IHByZXNlbmNlIiwiYXBwaWQiOiJmZ2hpNDU2N08wM0hST3hFandibjdrZ1hwQmhuaFd3diIsImlzcyI6Imh0dHBzOlwvXC9hcGkuZXBpY2dhbWVzLmRldlwvZXBpY1wvb2F1dGhcL3YxIiwiZG4iOiJLcm5icnkiLCJleHAiOjE1ODgyODYwODMsImlhdCI6MTU4ODI3ODg4Mywibm9uY2UiOiJuLUI1cGNsSXZaSkJaQU1KTDVsNkdvUnJDTzNiRT0iLCJqdGkiOiI2NGMzMGQwMjk4YTM0MzdjOGE3NGU1OTAxYzM0ODZiNSJ9.MZRoCRpjIb--dD7hxoo2GvjSPhUSNpOq1FhtShTBmzMJ1qlHFPzNaUiAEETAc3mabGPKyOxUP6Q1FBadr_P_UtbtB7kf34hN2VTv5czW6WOx1HdpjwUQZuxFyDc_aix7FCS0Egu4rZlC65b-B0FUVlial_s_FrH8ou5L_d-4I0KVpIwtv-b_M6EQ9jtLdQRfMaP6aV0rIerrbqFZ617Pe7XT4IO9jZFwM8F5aDTeDHkkOO41wyVibrm38799lP4B65RIv9CwbAL-TVmV1L5gFYITaZhi5ShfZzTvxAk-3Dxwp8c5JvcO68zpbya5gFSAfhsd7vt9YLU0gQR2uXq3Vw",
"refresh_token": "eyJ0IjoiZXBpY19pZCIsImFsZyI6IlJTMjU2Iiwia2lkIjoibldVQzlxSFVldWRHcnBXb3FvVXVHZkFIYmVWM2NsRnlsdFRYMzhFbXJKSSJ9.eyJhdWQiOiJ4eXphNzg5MWxoeE1WWUdDT043TGduS1paOEhRR0Q1SCIsInN1YiI6Ijk2MjZmNDQxMDU1MzQ5Y2U4Y2I3ZDdkNWE0ODNlYWEyIiwidCI6ImVwaWNfaWQiLCJhcHBpZCI6ImZnaGk0NTY3TzAzSFJPeEVqd2JuN2tnWHBCaG5oV3d2Iiwic2NvcGUiOiJiYXNpY19wcm9maWxlIGZyaWVuZHNfbGlzdCBwcmVzZW5jZSIsImlzcyI6Imh0dHBzOlwvXC9hcGkuZXBpY2dhbWVzLmRldlwvZXBpY1wvb2F1dGhcL3YxIiwiZG4iOiJLcm5icnkiLCJleHAiOjE1ODgzMDc2ODMsImlhdCI6MTU4ODI3ODg4MywianRpIjoiYzczYjA2NmUyZDU4NGVkNTk0NjZiOThiNzI3NzJiMjAifQ.O-eVa46NimubKwxe9SwlHxciivu0XWe1-DSL74mMiA_PpPoW0yKL9DfmsLxiPCwsRB5_hQTc6_FM7G1FyfKtX_VVAp90MZPkhCbAbfKmTpQVcL0Ya6kve4KMG8KxeLVfLLhubCbJTYlnDNVHobbpvpQtHd8Ys321ZNDJj05l_tnZzdgus-xmCO6orX4UP4wDd1jAOXXeqRT47OXuLCgSE0q6Osfh-ENPwh6ph1i7ld759xPV0oNcQb8XiPxnT6_FUmFugzG1YS1z9bTnVWmbP2RmYluue5VQm5EKGJZ91Alve8s2eNEtDfUqaBLZ45pqGkc1KjbYTtP0a_1ue2BpkQ",
"expires_in": 7200,
"expires_at": "2020-04-30T22:34:43.549Z",
"refresh_expires_in": 28800,
"refresh_expires_at": "2020-05-01T04:34:43.549Z",
"account_id": "9626f441055349ce8cb7d7d5a483eaa2",
"client_id": "xyza7891lhxMVYGCON7LgnKZZ8HQGD5H",
"application_id": "fghi4567O03HROxEjwbn7kgXpBhnhWwv"
}

You should always pass the access token as it is in the Authorization header to Epic Games services. For example: Authorization: Bearer eyJraWQiOiJ0RkM...

Endpoints

NameURL
OpenID Configurationhttps://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration
Authorizationhttps://www.epicgames.com/id/authorize
Tokenhttps://api.epicgames.dev/epic/oauth/v1/token
User Infohttps://api.epicgames.dev/epic/oauth/v1/userInfo
Token Infohttps://api.epicgames.dev/epic/oauth/v1/tokenInfo
JWKshttps://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json