Getting Started with Epic Account Services

How to set up Epic Account Services (EAS) with your product.

Epic Account Services (EAS) is a stand-alone offering of Epic Online Services (EOS). It is a separate family of Epic Account-specific services in addition to the identity provider-agnostic set of EOS services. Epic Online Services does not require using Epic Account Services, but you can always enable EAS as one of your EOS identity providers and use the Auth Interface. For more information about using identity provider-agnostic services, see the Connect Interface.

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

  • Signup for the Developer Portal and enable multi-factor authentication on the account.

  • Create your own organization or join an existing one. You need an Epic Account or an Admin role to proceed.

  • Create or pick a product to use Epic Account Services.

  • Download the latest version of EOS SDK. Check the EOS Quick Start guide for more details.

1. Accessing 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 EAS 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 standard EOS services, you license Epic Games as a service provider to process the data of your users on your behalf. But with EAS, Epic Games manages the user data and authentication flows to expose this data and functionality on your users' 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 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.

3. Authenticating Epic Games Users with the EOS SDK

Using an Epic 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:

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

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