Auth Web APIs

Use the Auth interface Web APIs to authenticate for Epic Account Services Web APIs.

11 mins to read

Epic Online Services uses the OAuth 2.0 protocol for authentication and authorization, supporting common-use cases for web servers and client-side applications. Epic has also introduced custom grant types for some specific use cases.

Before starting, you will need to obtain OAuth 2.0 client credentials from Epic. These will be in the form of a Client ID and Client Secret, and will be used when requesting an access token from the Epic authorization server. See our guide on Getting Started with Epic Account Services for more details.

Scenarios

Game Client on the Epic Games Store

A game client launched from the Epic Games Store will authenticate with Epic’s authorization server using a one-time use exchange code. This exchange code is generated by the Epic Launcher and passed to the game client as a command-line argument.

When the game client is launched, it will make a request to the Epic token endpoint that includes the client credentials and exchange code. The response will include an access token, information about the client and account that were authenticated, and an optional refresh token.

The game client will include the access token on all requests to Epic services. The access token can also be passed to trusted game servers for verification, or for use in service-to-service requests.

When applicable, a refresh token will also be included in the token response. The game client will need to use the refresh token if the access token expires. This typically occurs within 2 hours after the access token is issued.

EGS Client Auth flow

Diagram illustrating Epic Games Launcher authentication flow. Click image to enlarge.

Web Server Applications

For server-side applications, the flow will begin by taking the user through the Epic authorization flow on a web browser so that it can obtain an authorization code. The user will be asked to log in using their Epic Games account, and may be asked to authorize your application. Once authorized, the user agent will redirect back to your web application with an authorization code included as a query parameter.

After the redirect, the web server will make a request to the Epic token endpoint using the client credentials and authorization code. The response will include an access token, as well as information about the client and account that were authenticated.

The web server will include the access token on all requests to Epic services.

Authentication

As the first step in the authentication flow, the user must authenticate with Epic Account Services. We only support OAuth 2.0 for authentication, with additional custom grant types.

Once the client has the necessary information to request a token (including the exchange code, authorization code, and user credentials), it begins by requesting an access token.

Requesting an Access Token

To request an access token, the client must make an HTTP request to the Epic token endpoint, passing the client credentials (Client ID and Secret) and user credentials.

The Epic token endpoint is https://api.epicgames.dev/epic/oauth/v1/token. If you want to indicate that an access token is no longer needed, use https://api.epicgames.dev/epic/oauth/v1/revoke. This endpoint implements RFC 7009 - OAuth 2.0 Token Revocation.

The client credentials will be passed in the Authorization header using Basic authorization. This endpoint supports the following post parameters:

Parameter name Description
grant_type The grant type being used: exchange_code, password, refresh_token, or client_credentials.
deployment_id The deployment ID that the client is trying to authenticate with. This will impact interactions with other services that require a deployment. If the deployment is not public, only users who have been entitled will be able to log in. For more information on deployments and deployment IDs see Product, Sandbox, and Deployment IDs. Note: You must use this unique identifier to use the Ecommerce APIs, and to request access tokens used by game clients.
scope Space-delimited list of scopes (permissions) that will be requested from the user. For example: basic profile, friends_list, and presence
For the password grant type
The password grant type can be used during development, but will only be allowed for accounts that are members of the organization that this product is associated with.
Note: The password grant type does not work with 2FA enabled.
username The username (email address) for the account; only used with the password grant type.
password The password for the account; only used with the password grant type.
For the exchange_code grant type
exchange_code The exchange code passed by Launcher to the game client; only used with the exchange_code grant type.
For the authorization_code grant type
code The authorization code received from the authorization server.
For the client_credentials grant type (see Web Authorization )
client_id The OAuth Client ID for your application.
client_secret The OAuth Client Secret for your application.

These parameters should be in the request body. Query parameters will be ignored.

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=password&
deployment_id=foo&
scope=basic_profile friends_list presence&
username=user@example.com&
password=s3cr3t

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 expire date in ISO 8601 format.
account_idThe Epic 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 expire date in ISO 8601 format.

The following snippet shows a sample response:

{
"scope": "basic_profile friends_list presence",
"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"
}