Connect Web APIs

Use the Connect interface Web API to authenticate with EOS Game Services Web APIs.

7 mins to read

You can access EOS Game Services through Web APIs that require access tokens to identify the authenticated clients that make the requests. Clients can request access tokens either as an independent client (client access tokens) or on behalf of a user (user access tokens).

For example, a web application might may authenticate users to provide account-linking management functionality for players. An independent client could be a publisher-hosted backend that orchestrates voice chat rooms hosted by the EOS Voice backend service.

Request an EOS Access Token

The EOS Connect backend provides an OAuth 2.0 token endpoint to request access tokens for the EOS Game Services Web APIs.

The EOS Connect token endpoint is as follows:

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

Clients can request two types of access tokens:

  • Client access tokens: used by independent clients interacting with backend services for general product level access.
  • User access tokens: used by clients interacting with backend services on behalf of authenticated users.

When a client requests an access token, it must provide a valid set of Client Credentials for a Product. You can create clients for each product in the Developer Portal in Product Settings, and receive individual client policies.

A client can pass Client Credentials in one of two ways:

  • With the standard Authorization HTTP header or
  • With the POST parameters.

Token Request

HTTP Request POST /auth/v1/oauth/token
HTTP Headers
NameValue
Authorization Basic <Base64(ClientId:ClientSecret)>. Example: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type application/x-www-form-urlencoded
POST Body Parameters
NameDescription
grant_type For client access, use client_credentials. For user access, use external_auth.
client_id Client Credentials ID. Required if the Authorization HTTP header is not used.
client_secret Client Credentials Secret. Required if the Authorization HTTP header is not used.
nonce An arbitrary string value provided by the client that provides added security. It is included in the API response for the client, to verify the correct nonce value. Required for user access.
deployment_id Target EOS deployment to request access for Required for user access.
external_auth_token External authentication token that identifies the user account in the external account system. Required for user access.
external_auth_type Identifies the external authentication token’s type. Required for user access. The possible values are: amazon_access_token, apple_id_token, discord_access_token, epicgames_access_token, epicgames_id_token, gog_encrypted_sessionticket, google_id_token, itchio_jwt, itchio_key, nintendo_id_token, oculus_userid_nonce, openid_access_token, psn_id_token, steam_access_token, steam_encrypted_appticket, xbl_xsts_token

Example Request

curl -X "POST" "https://api.epicgames.dev/auth/v1/oauth/token" \
-H "Content-Type:application/x-www-form-urlencoded" \
-H "Accept:application/json" \
-H "Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0" \
-d "grant_type=client_credentials&deployment_id=<deploymentId>"

Token Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameDescription
access_token Generated access token as a JSON Web Token (JWT) string. The access token describes the authenticated client and user.
expires_at Token expiration time. Contains a NumericDate number value, describing the time point in seconds from the Unix epoch.
expires_in Token lifetime. Seconds since the issue time to when the token will expire.
nonce Arbitrary string value provided by the client in the token request. Used by clients for added security. When receiving an access token in HTTP response, the client can verify that the token response includes the expected nonce value.
organization_id Your organization identifier.
product_id Your product identifier.
sandbox_id Your sandbox identifier
deployment_id Your deployment identifier.
features List of features that the client is permitted to access. Features can be enabled for clients in the Developer Portal.
organization_user_id Identifies the EOS user uniquely across products within your organization. Included for user access tokens.
product_user_id The authenticated EOS Product User ID. Included for user access tokens.
id_token An ID token that securely identifies the EOS Product User. Included for user access tokens.

The received access_token is used to call EOS Game Services Web APIs by providing it in the Authorization HTTP header as a Bearer token. For example: Authorization: Bearer <access_token>.

Example Response

{
"access_token" : "<Access Token>",
"token_type" : "bearer",
"expires_at" : "2021-06-11T23:10:53.491Z",
"expires_in" : 3599,
"features" : ["Matchmaking", "Voice"],
"organization_id" : "<Organization ID>",
"product_id" : "<Product ID>",
"sandbox_id" : "<Sandbox ID>",
"deployment_id" : "<Deployment ID>"
}

Query External Accounts

The request queryExternalAccountsForAnyUser returns associated Product User IDs from a list of external account IDs.

Policy

The client must have the queryExternalAccountsForAnyUser client policy action enabled for the Connect feature.

Authorization

This call requires Bearer Token authorization with an EOS client access token.

QueryExternalAccounts Request

HTTP Request GET /user/v1/accounts
HTTP Headers
NameValue
Authorization Bearer <EOS client access token>
HTTP Query Parameters
NameTypeDescription
accountId Array <String> A list of external account IDs to query Product User IDs for. The maximum number of input account IDs is 16.
identityProviderId String A supported identity provider. Allowed values are: Amazon, apple, discord, epicgames, gog, google, itchio, nintendo, oculus, Openid, psn, steam, xbl.
environment String If the external account system uses isolated account environments, you must specify an environment. See the platform provider’s documentation for the possible environment values. Otherwise, you must exclude this field.

Example Request

curl -X "GET" "https://api.epicgames.dev/user/v1/accounts?accountId=<ExternalAccountId_1>&accountId=<ExternalAccountId_2>&identityProviderId=<IdentityProviderId>" \
-H "Accept:application/json" \
-H "Authorization: Bearer <EOS client access token>"`

QueryExternalAccounts Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameTypeDescription
ids Object <String, String> Key is an external account ID. Value is a Product User ID. Object that maps external account IDs to Product User IDs. If the external account ID is not associated with a Product User ID, it will be excluded from the response.

Example Response

{
"ids": {
"<ExternalAccountId_1>": "<ProductUserId_1>",
"<ExternalAccountId_2>": "<ProductUserId_2>",
}
}

Query Product Users

The request queryProductUsersForAnyUser returns associated accounts from a list of Product User IDs.

Policy

The client must have the queryProductUsersForAnyUser client policy action enabled for the Connect feature.

Authorization

This call requires Bearer token authorization with an EOS client access token.

QueryProductUsers Request

HTTP Request GET /user/v1/product-users
HTTP Headers
NameName
Authorization Bearer <EOS client access token>
HTTP Query Parameters
NameTypeDescription
productUserId Array <String> A list of Product User IDs to query accounts for. The maximum number of input Product User IDs is 16.

Example Request

curl -X "GET" "https://api.epicgames.dev/user/v1/product-users?productUserId=<ProductUserId_1>&productUserId=<ProductUserId_2>" \
-H "Accept:application/json" \
-H "Authorization: Bearer <EOS client access token>"

QueryProductUsers Response

HTTP Response 200 - OK: Success.
HTTP Headers
Name Value
Content-Type application/json
JSON Payload
NameTypeDescription
productUsers Object <String, ProductUser> Key is a Product User ID.

Object that maps Product User IDs to accounts. If the Product User ID is not found, it will be excluded from the response.

ProductUser Schema

ProductUser
NameTypeDescription
accounts Array<Account> Accounts associated with the Product User.

Account Schema

Account
NameTypeDescription
accountId String External Account ID.
identityProviderId String

Identity provider of the external account. Supported providers are:

  • amazon
  • apple
  • discord
  • epicgames
  • gog
  • google
  • itchio
  • nintendo
  • oculus
  • openid
  • psn
  • steam
  • xbl

New identity providers may be added to the list.

displayName String (optional) Display name of the user.
lastLogin String Last login time, ISO 8601.

Example Response

{
"productUsers": {
"<ProductUserId_1>": {
"accounts": [
{
"accountId": "<AccountId_1>",
"displayName": "<DisplayName_1>",
"identityProviderId": "<IdentityProvider_1>",
"lastLogin": "2022-03-18T11:55:44Z"
}
]
},
"<ProductUserId_2>": {
"accounts": [
{
"accountId": "<AccountId_2>",
"displayName": "<DisplayName_2>",
"identityProviderId": "<IdentityProvider_2>",
"lastLogin": "2022-01-05T10:25:38Z"
}
]
}
}
}