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 | |||
| Name | Value | ||
Authorization | Basic <Base64(ClientId:ClientSecret)>. Example: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0 | ||
Content-Type | application/x-www-form-urlencoded | ||
| POST Body Parameters | |||
| Name | Description | ||
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
Token Response
| HTTP Response 200 - OK: Success. | ||
| HTTP Headers | ||
| Name | Value | |
Content-Type | application/json | |
| JSON Payload | ||
| Name | Description | |
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
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 | |||
| Name | Value | ||
Authorization | Bearer <EOS client access token> | ||
| HTTP Query Parameters | |||
| Name | Type | Description | |
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. For Xbox, use xbl_retail. | |
Example Request
QueryExternalAccounts Response
| HTTP Response 200 - OK: Success. | ||
| HTTP Headers | ||
| Name | Value | |
Content-Type | application/json | |
| JSON Payload | ||
| Name | Type | Description |
ids | Object <String, String> | Object that maps external account IDs to Product User IDs. The key is an external account ID. The value is a Product User ID. If the external account ID is not associated with a Product User ID, it will be excluded from the response. |
Example Response
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 | ||
| Name | Name | |
Authorization | Bearer <EOS client access token> | |
| HTTP Query Parameters | ||
| Name | Type | Description |
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
QueryProductUsers Response
| HTTP Response 200 - OK: Success. | ||
| HTTP Headers | ||
| Name | Value | |
Content-Type | application/json | |
| JSON Payload | ||
| Name | Type | Description |
productUsers | Object <String, ProductUser> | Object that maps Product User IDs to accounts. The key is a Product User ID. If the Product User ID is not found, it will be excluded from the response. |
ProductUser Schema
| ProductUser | ||
| Name | Type | Description |
accounts | Array<Account> | Accounts associated with the Product User. |
Account Schema
| Account | ||
| Name | Type | Description |
accountId | String | External Account ID. |
identityProviderId | String | Identity provider of the external account. New identity providers may be added to the list. This is the default list of supported providers:
|
displayName | String (optional) | Display name of the user. |
lastLogin | String | Last login time as defined in ISO 8601. |