Epic Online Services Interface: Auth Interface

The Auth Interface lets players (users) log into their Epic Account from your game (product) so they can access the features provided by Epic Account Services (EAS), such as Friends, Presence, UserInfo and Ecom interfaces. The Auth Interface handles Epic account-related interactions with EOS, providing the ability to authenticate users and obtain access tokens.

The following guides are available:

• Logging In

These functions are provided for handling authentication:

• eos_auth_add_notify_login_status_changed
• eos_auth_copy_id_token
• eos_auth_copy_user_auth_token
• eos_auth_delete_persistent_auth
• eos_auth_get_login_status
• eos_auth_get_selected_account_id
• eos_auth_link_account
• eos_auth_login
• eos_auth_logout
• eos_auth_query_id_token
• eos_auth_remove_notify_login_status_changed
• eos_auth_verify_id_token

These are the constants used by this module:

• EOS_AUTH_SCOPE_FLAGS
• EOS_LOGIN_CREDENTIAL_TYPE
• EOS_EXTERNAL_CREDENTIAL_TYPE
• EOS_LOGIN_STATUS

These are the structs used by this module:

• AuthTokenInfo
• IdWebTokenInfo

Back To Top

Epic Online Services Function: EOS_Auth_AddNotifyLoginStatusChanged

This function registers to receive login status updates.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_add_notify_login_status_changed()

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_auth_add_notify_login_status_changed();

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_add_notify_login_status_changed")
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Function: EOS_Auth_CopyIdToken

This function fetches an ID token for an Epic Account ID. ID tokens are used to securely verify user identities with online services. The most common use case is using an ID token to authenticate the local user by their selected account ID, which is the account ID that should be used to access any game-scoped data for the current application. An ID token for the selected account ID of a locally authenticated user will always be readily available. To retrieve it for the selected account ID, you can use eos_auth_copy_id_token directly after a successful user login.

Syntax:

eos_auth_copy_id_token(account_id)

Returns:

IdWebTokenInfo

Example:

var _struct = eos_auth_copy_id_token(account_id);
if(_struct.status == EOS_RESULT.SUCCESS)
{
    json_web_token = _struct.json_web_token;
}

The above code shows an example of how the function should be used. The token associated with the provided account ID is returned inside the struct, alongside other useful information.

Back To Top

Epic Online Services Function: EOS_Auth_CopyUserAuthToken

This function fetches a user auth token for an Epic Account ID. A user authentication token allows any code with possession (backend/client) to perform certain actions on behalf of the user. Because of this, for the purposes of user identity verification, the eos_auth_copy_id_token should be used instead.

Syntax:

eos_auth_copy_user_auth_token(account_id)

Returns:

AuthTokenInfo

Example:

var _struct = eos_auth_copy_user_auth_token(account_id);
if(_struct.status == EOS_RESULT.SUCCESS)
{
     var _access_token = _struct.access_token;
}

The above code shows an example of how the function should be used. The access token associated with the provided account ID is returned inside the struct alongside other useful information.

Back To Top

Epic Online Services Function: EOS_Auth_DeletePersistentAuth

This function deletes a previously received and locally stored persistent auth access token for the currently logged in user of the local device. On Desktop and Mobile platforms, the access token is deleted from the keychain of the local user and a backend request is made to revoke the token on the authentication server. On Console platforms, even though the caller is responsible for storing and deleting the access token on the local device, this function should still be called with the access token before its deletion to make the best effort in attempting to also revoke it on the authentication server. If the function would fail on Console, the caller should still proceed as normal to delete the access token locally as intended.

Syntax:

eos_auth_delete_persistent_auth(refresh_token)

Returns:

N/A

Example:

eos_auth_delete_persistent_auth(refresh_token);

The above code shows an example of how the function should be used. The refresh token provided will be revoked and invalidated.

Back To Top

Epic Online Services Function: EOS_Auth_GetLoginStatus

This function fetches the EpicGames login status for an Epic Account ID.

Syntax:

eos_auth_get_login_status(account_id)

Returns:

EOS_LOGIN_STATUS

Example:

switch(eos_auth_get_login_status(account_id))
{
    case EOS_LOGIN_STATUS.NOT_LOGGED_IN:
        draw_text(100, 190, "Login Status: Not Logged In");
        break;

    case EOS_LOGIN_STATUS.USING_LOCAL_PROFILE:
        draw_text(100, 190, "Login Status: Using Local Profile");
        break;

    case EOS_LOGIN_STATUS.LOGGED_IN:
        draw_text(100, 190, "Login Status: Logged In");
        break;
}

The above code shows an example of how the function should be used. A login status constant is returned and checked against the provided built-in constants.

Back To Top

Epic Online Services Function: EOS_Auth_GetSelectedAccountId

This function fetches the selected account ID to the current application for a local authenticated user.

Syntax:

eos_auth_get_selected_account_id(account)

Returns:

String

Example:

var _account_id = eos_auth_get_selected_account_id(account_id);

The above code shows an example of how the function should be used.

Back To Top

Epic Online Services Function: EOS_Auth_LinkAccount

This function links an external account by continuing the previous login attempt with a continuance token. On Desktop and Mobile platforms, the user will be presented the Epic Account Portal to resolve their identity. On Console, the user will login to their Epic Account using an external device, e.g. a mobile device or a desktop PC, by browsing to the presented authentication URL and entering the device code presented by the game on the console. On success, the user will be logged in at the completion of this action. This will commit this external account to the Epic Account and cannot be undone in the SDK.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_link_account(account_id, scope_flags)

Returns:

Real

Triggers:

Social Async Event

Example:

var _scope_flags = EOS_AUTH_SCOPE_FLAGS.BASIC_PROFILE | EOS_AUTH_SCOPE_FLAGS.FRIENDS_LIST | EOS_AUTH_SCOPE_FLAGS.PRESENCE;
identifier = eos_auth_login(account_id, _scope_flags);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_link_account")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Function: EOS_Auth_Login

This function logs in / authenticates with user credentials.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_login(type, scope_flags, id, token, external_type)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_auth_login(
                EOS_LOGIN_CREDENTIAL_TYPE.EXCHANGE_CODE,
                EOS_AUTH_SCOPE_FLAGS.BASIC_PROFILE | EOS_AUTH_SCOPE_FLAGS.FRIENDS_LIST | EOS_AUTH_SCOPE_FLAGS.PRESENCE,
                "",
                code,
                -1);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_login")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Function: EOS_Auth_Logout

This function signs the player out of the online service.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_logout(account_id)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_auth_logout(account_id);

The code sample above save the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_logout")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Function: EOS_Auth_QueryIdToken

This function queries the backend for an ID token that describes one of the merged account IDs of a local authenticated user. The ID token can be used to impersonate a merged account ID when communicating with online services. An ID token for the selected account ID of a locally authenticated user will always be readily available and does not need to be queried explicitly.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_query_id_token(account_id, account_id_target)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_auth_query_id_token(account_id, account_id);

The code sample above save the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_query_id_token")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Function: EOS_Auth_RemoveNotifyLoginStatusChanged

This function unregisters from receiving login status updates.

Syntax:

eos_auth_remove_notify_login_status_changed(id)

Returns:

N/A

Example:

var _handle = eos_auth_add_notify_login_status_changed();
//...
//...later
//...
eos_auth_remove_notify_login_status_changed(_handle);

The code sample above enables the login status notifications (eos_auth_add_notify_login_status_changed) and later disables them by referring to the previously generated handle.

Back To Top

Epic Online Services Function: EOS_Auth_VerifyIdToken

This function verifies a given ID token for authenticity and validity.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_auth_verify_id_token(account_id, json_web_token)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_auth_verify_id_token(account_id, json_web_token);

The code sample above keeps a handle that can be used inside a Social Async Event.

if (async_load[? "type"] == "eos_auth_verify_id_token")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.SUCCESS)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

Back To Top

Epic Online Services Enum: EOS_EAuthScopeFlags

List of the supported scope flags associated with the login API calls:

These constants are referenced by the following functions:

• eos_auth_link_account
• eos_auth_login

Back To Top

Epic Online Services Constant: EOS_EExternalCredentialType

List of the supported identity providers to authenticate a user. The type of authentication token is specific to each provider. Tokens in string format should be passed as-is to the function.

These constants are referenced by the following functions:

• eos_auth_login
• eos_connect_login

Back To Top

Epic Online Services Enum: EOS_ELoginCredentialType

This enum holds all possible types of login methods, availability depends on permissions granted to the client.

These constants are referenced by the following functions:

• eos_auth_login

Back To Top

Epic Online Services Enum: EOS_ELoginStatus

These constants are used to describe the Login status of a given account or connection and are returned by the following functions:

These constants are referenced by the following functions:

• eos_auth_add_notify_login_status_changed
• eos_auth_get_login_status
• eos_connect_add_notify_login_status_changed

Back To Top

This struct contains detailed info on an access token used for authentication.

This struct is referenced by the following functions:

• eos_auth_copy_user_auth_token

Back To Top

This struct contains details on an ID Token in the form of a JSON Web Token string.

This struct is referenced by the following functions:

• eos_auth_copy_id_token