Getting Started with Epic Account Services

How-to guide for setting up a project with EAS

This guide will walk you through the process of creating your first EAS application and setting up your game to use Epic Account Services.

Applications within Epic Account Services are defined with their own configuration, life cycle, and associated data. The simplest way to understand an application is to view it as an entity on behalf of which a developer or a piece of software asks the user for permission to access their data.

0. Prerequisites

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

  1. Signup for the Developer Portal at https://dev.epicgames.com/portal and enable multi-factor authentication on the account.

  2. Create your own organization or join an existing one. Minimally you will need an Epic Account or an Admin role to proceed.

  3. Create or pick a product to use Epic Account Services with.

  4. Download the latest version of EOS SDK.

Check the EOS Quick Start for more details.

1. Accessing Epic Account Services

To access Epic Account Services, navigate to the corresponding section under a product configuration. You can do this from the Organization dashboard:

Click to enlarge image.

Alternatively, you can click the Epic Account Services tile on the Product dashboard, or the link within the Product navigation panel:

Click to enlarge image.

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

2. Accepting the License Agreement

Acceptable use of Epic Account Services is defined in the Service Addendum for Epic Account Services. Before you can use the services, you will need to review and accept this addendum. You might also want to review the Epic Games Privacy Policy document to understand how Epic Games collects, uses and shares user data.

Your organization can be set up with an Individual or a Company entity type. If an organization is set up with a Company entity type, then each license agreement version needs to be accepted just once per organization. Otherwise, each individual member with access to the EAS dashboard would need to accept agreements individually.

Note that when you use Epic Account Services, you and Epic Games switch roles in the data handling process. With Standard EOS services, you're licensing Epic Games as a service provider to process the data of your players on your behalf. With Epic Account Services, Epic Games manages the user data and authentication flows and exposes this data and functionality on users' behalf, with their consent. From your end, you agree to use the data for specifically permitted uses only, as defined in the Service Addendum for Epic Account Services.

Click to enlarge image.

After accepting the agreement, the EAS dashboard will display and you can start the setup process for your application.

3. Setting Up an EAS 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.

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.

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.

Epic Account Services is available in a Preview mode, and is a subject to temporary limitations. Specifically, the Application Brand Review process is currently under construction and is coming soon. Stay tuned!

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.

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.

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.

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.

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.

Click to enlarge image.

At this point you have completed the EAS 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.

Click to enlarge image.

4. Authenticating Epic Games Users With EOS SDK

Use of Epic Account requires no special setup in the EOS SDK. However, you must use a login type that is appropriate for your target platform, and you must remember to include the scopes you want the user to consent to in the login call. 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 will open a default system web browser that prompts the user to login and review the access application requests. Refer to Authorization and Consent Management for more information regarding the user experience on login.

For more detailed information about API usage and preferred login types per platform, see Auth Interface.

5. Authenticating Epic Games Users on a Web Site

We support OpenID Connect Core 1.0, for authenticating users on websites and web applications, using the authorization code flow. Before you begin, you will need to configure an Application and Client credentials.

User Authorization

To initiate the flow, your application will need to redirect the user to the authorization page where they will be asked to login to their Epic Games account. The authorization URL is:

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. This should contain a space-delimited list of the required permissions. For example:

scope=basic_profile friends_list

The redirect URI in the authorization request will need to be configured for the Client in the Dev Portal.

After the user logs in, they will be asked to approve the requested permissions. After, they will be redirected back to your application with a code parameter. The code will be used when requesting an access token.

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

The following is an example redirect after the user is authenticated:

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

Requesting an Access Token

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

The client credentials will be passed in the Authorization header using basic authorization.

In the request, you will also need to specify the authorization_code grant type and include the code and redirect URI 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:

Response

Description

access_token

The 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_in

The number of seconds until the token expires.

expires_at

The expiration date in ISO 8601 format.

account_id

The Epic Account ID for the user that the token was generated for.

client_id

The Client ID which was used to generate this token.

application_id

The Application ID which the Client is associated with.

token_type

The type of token generated, value will always be bearer.

refresh_token

The 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_expires

The number of seconds until the refresh token expires.

refresh_expires_at

The refresh token experiation 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"
}

The access token should always be passed as is in the Authorization header to Epic services. For example: Authorization: Bearer eyJraWQiOiJ0RkM....

Endpoints

Name

URL

OpenID Configuration

https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration

Authorization

https://www.epicgames.com/id/authorize

Token

https://api.epicgames.dev/epic/oauth/v1/token

User Info

https://api.epicgames.dev/epic/oauth/v1/userInfo

Token Info

https://api.epicgames.dev/epic/oauth/v1/tokenInfo

JWKs

https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json