Ban and restrict accounts

Last updated on December 19, 2024

Introduction

The user ban feature allows you to restrict a user's access to your game or specific features in your game. You can ban players and lift existing bans in the AccelByte Gaming Services (AGS) Admin Portal.

AGS allows you to impose the following banning methods:

• Account Ban: Revoke access tokens for banned players.
• Feature Ban: Invalidate access tokens for specific in-game features.
• Device Ban: Restrict access to your game from a specific device using its unique ID.

caution

All ban actions will revoke existing access tokens.

• If it's an account ban, the refresh_token will also be revoked. This means the user can't login using their credentials or a refresh_token.
• If it's a feature ban, the refresh_token will still be valid. This means the user can use the refresh_token to log in immediately.
• If the ban is on the game namespace, it will only affect that game namespace.
• If the ban is on the publisher namespace, it will affect both the publisher and the game namespace.

Prerequisites

• Make sure you have access to the Admin Portal.

• Make sure you have the following permissions:

  Usage	Permissions	Action
  Ban a player	ADMIN:NAMESPACE:{namespace}:USER:{userId}:BAN	CREATE
  Enable or disable a player's Ban	ADMIN:NAMESPACE:{namespace}:USER:{userId}:BAN	UPDATE
  Retrieve ban types and reasons	ADMIN:BAN	READ

Ban scope

• If you ban a player at the publisher namespace level, the ban will apply to all the namespaces in it.

AGS Shared Cloud

In Shared Cloud tier, this applies to the studio namespace, which has the same function as the publisher namespace in the Private Cloud tier.

• If you ban a player at the game namespace level, the ban only applies to the specific game namespace.

Ban a player by account

1. On the Admin Portal sidebar, go to Lookup Users.

2. Search for the player you want to ban using the corresponding credentials.

3. Click View in Action to open the account. The user account details appear.

4. Click Bans, and then click Add Ban to ban the selected user.

   

   The Add Ban settings appear.

Add the user ban details

1. Choose the Ban Type.

   Feature Ban Details

   If you choose Feature Ban, you must choose the feature you want to restrict. A list of the features that players can be banned from can be found in the following table.

   Feature Restriction	Description
   CHAT_SEND	Player is banned from sending a message
   CHAT_ALL	Player is banned from both sending and receiving messages
   ORDER_AND_PAYMENT	Player is banned from making purchases in-game
   STATISTICS	Player will not have their statistics recorded
   LEADERBOARD	Player will not appear on any leaderboards
   MATCHMAKING	Player is banned from matchmaking

2. In Ban Expiration, select one of the following:

   • Set by duration: Enter the number of minutes, hours, or days you want the player to be banned for. The ban expires after this duration.

   • Set by expiration date: Enter the date and time you want the ban to expire.

   • Never: Set a permanent ban.

     

3. In Reason, choose a reason for the ban.

   Reason Details

   The following table lists the reasons available for a ban:

   Reason	Description
   VIOLENCE	Player is banned for posting violent content
   HARASSMENT	Player is banned for harassing other players
   HATEFUL_CONDUCT	Player is banned for acting hatefully towards other players
   OFFENSIVE_USERNAME	Player is banned for having an offensive username
   IMPERSONATION	Player is banned for impersonating other players
   MALICIOUS_CONTENT	Player is banned for posting malicious content such as spam, scams, etc.
   SEXUALLY_SUGGESTIVE	Player is banned for posting sexually explicit or suggestive content
   SEXUAL_VIOLENCE	Player is banned for acting sexually violent or exploiting other players
   EXTREME_VIOLENCE	Player is banned for extremely violent content, such as gore
   UNDERAGE_USER	Player is banned for being underage
   CHEATING	Player is banned for cheating
   TOS_VIOLATION	Player is banned for violating the Terms of Service

4. Type a comment to include any relevant information about the ban.

5. Select the Notify user via email checkbox to send a ban notification to the player via email.

   info

   Players that log into your game using third-party credentials may only have a headless account in the Admin Portal. This means their account won't have an associated email address. Only players that have registered an account in your game (or platform), or have upgraded their headless account by registering an email address in your game, will be able to receive an email notification if they're banned. For more information, see How accounts work.

   

6. Click Ban. The new ban appears in the Bans list.

   

Ban a player by device

note

The device ban feature is only available in game namespaces.

AGS Shared Cloud

The device ban feature is not yet supported in AGS Shared Cloud.

1. On the Admin Portal sidebar, go to Lookup Users.

2. Search for the player you want to ban using their credentials. The search results appear.

   

3. Click View in Action to open the account. The user account details appear.

   

4. Click Bans, and then click Add Ban to ban the selected user. The Add Ban settings appear.

   

Add the device ban details

1. In Ban type, choose Device Ban.

2. In Device ID, choose the device you want to ban. A list of the devices used to log in by this player appears in this menu.

3. In Ban Expiration, select one of the following:

   • Set by duration: Enter the number of minutes, hours, or days you want the player to be banned for. The ban expires after this duration.
   • Set by expiration date: Enter the date and time you want the ban to expire.
   • Never: Set a permanent ban.

4. In Reason, choose a reason for the ban dropdown list.

5. Type a Comment to include any relevant information about the ban.

6. Click Ban. The ban appears in the Bans list.

Enable and disable ban

You can reactivate an expired or disabled ban on a player, or lift an existing ban on a player. To do this:

1. On the Admin Portal sidebar, go to Lookup Users.

2. Search the user account to view the account edit history. The search results appear.

3. Browse the list to find the account you are looking for and click View in the Action column of the account listing to open it.

4. Click Bans to ban the selected user. All the bans that have ever been applied to the player are displayed.

   

5. Click Disable under the Action column of the selected ban to disable the ban or click Enable under the Action column to enable the selected ban.

   

6. The Disable Ban confirmation message appears. Click Enable or Disable to ban or un-ban the player.

   

7. After you disable the ban, the player will be able to access the game or the feature they were banned from. If you enable a ban for a player, the player will now be banned from accessing the game or from the specific feature.

Ban or un-ban a player

Use the following server-side code to ban a player.

Unity

string playerUserID = "exampleuserid2434";
BanType banType = BanType.LOGIN;
BanReason banReason = BanReason.CHEATING;
var banEndDate = System.DateTime.UtcNow.AddDays(value: 365);
banEndDate = banEndDate.AddDays(365);
string comment = "This player was caught cheating";
bool notifyUserEmail = false;
string banId = string.Empty;

AccelByteSDK.GetServerRegistry().GetApi().GetUserAccount().BanUser(playerUserID, banType, banReason, banEndDate, comment, notifyUserEmail, result =>
{
    if (!result.IsError)
    {
        Debug.Log("Success. The player is banned.");
    }
    else
    {
        Debug.Log("Failed to ban the player. Error : " + result.Error.ToString());
    }
});

Go Extend SDK

usersService := &iam.UsersService{
    Client:          factory.NewIamClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
userId := "exampleuserid2434"
ban := "LOGIN"
reason := "CHEATING"
endDate := "2024-12-31T00:00:00"
comment := "This player caught cheating"
skipNotif := true
input := &users.AdminBanUserV3Params{
    Body:      &iamclientmodels.ModelBanCreateRequest {
        Ban: &ban,
        Reason: &reason,
        EndDate: &endDate,
        Comment: &comment,
        SkipNotif: &skipNotif,
    },
    Namespace: namespace,
    UserID:    userId,
}
result, err := usersService.AdminBanUserV3Short(input)

Python Extend SDK

result, error = iam_service.admin_ban_user_v3(
    body=iam_models.ModelBanCreateRequest()
    .with_ban("LOGIN")
    .with_comment("This player was caught cheating.")
    .with_end_date("2030-12-31T00:00:00.000Z")
    .with_reason("CHEATING")
    .with_skip_notif(False),
    user_id=user_id,
)
if error:
    exit(error)

Java Extend SDK

Users usersWrapper = new Users(sdk);

String userId = "<user id>";
//ban for 1 year
LocalDateTime now = LocalDateTime.now();
LocalDateTime nextYear = now.plusYears(1);
String endDate = nextYear.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);

ModelBanCreateRequest body = ModelBanCreateRequest.builder()
    .ban("LOGIN")
    .reason("CHEATING")
    .comment("This player caught cheating")
    .skipNotif(true)
    .endDate(endDate)
    .build();
ModelUserBanResponseV3 response;
try {
    response = usersWrapper.adminBanUserV3(AdminBanUserV3.builder()
        .namespace("<namespace>")
        .userId(userId)
        .body(body)
        .build());
} catch (Exception e) {
    // Do something when failed
    return;
}

if (response == null) {
    // Null response from server
} else {
    // Do something when successful
}

C# Extend SDK

string userId = "<user id>";

//ban for 1 year
string endDate = DateTime.Now.AddYears(1).ToString("o");

var response = sdk.Iam.Users.AdminBanUserV3Op
    .Execute(new ModelBanCreateRequest()
    {
        Ban = "LOGIN",
        Reason = "CHEATING",
        Comment = "This player caught cheating",
        SkipNotif = true,
        EndDate = endDate
    }, sdk.Namespace, userId);
if (response != null)
{
    string banId = response.BanId!;
    //do something when success
}

banId could be used to unban the player.

Unity

AccelByteSDK.GetServerRegistry().GetApi().GetUserAccount().ChangeUserBanStatus(
    userId: playerUserID,
    banId: banId,
    enabled: false,
    (result) =>
    {
        if (result.IsError)
        {
            Debug.Log("Success. Player is unbanned.");
        }
        else
        {
            Debug.Log("Failed to un-ban the player. Error : " + result.Error.ToString());
        }
    }
);

Go Extend SDK

usersService := &iam.UsersService{
    Client:          factory.NewIamClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
input := &users.AdminUpdateUserBanV3Params{
    Body:      &iamclientmodels.ModelBanUpdateRequest{
        Enabled: &enabled,
    },
    BanID:     banId,
    Namespace: namespace,
    UserID:    userId,
}
result, err := usersService.AdminUpdateUserBanV3Short(input)

Python Extend SDK

result, error = iam_service.admin_update_user_ban_v3(
    body=iam_models.ModelBanUpdateRequest()
    .with_enabled(False)
    .with_skip_notif(False),
    ban_id="BanId",
    user_id=user_id,
)
if error:
    exit(error)

Java Extend SDK

Users usersWrapper = new Users(sdk);

String userId = "<user id>";
String banId = "<ban id>";
ModelBanUpdateRequest body = ModelBanUpdateRequest.builder()
    .enabled(false)
    .skipNotif(false)
    .build();
ModelUserBanResponseV3 response;
try {
    response = usersWrapper.adminUpdateUserBanV3(AdminUpdateUserBanV3.builder()
            .namespace("<namespace>")
            .userId(userId)
            .banId(banId)
            .body(body)
            .build());
} catch (Exception e) {
    // Do something when failed
    return;
}

if (response == null) {
    // Null response from server
} else {
    // Do something when successful
}

C# Extend SDK

string userId = "<user id>";
string banId = "<ban id>";

var response = sdk.Iam.Users.AdminUpdateUserBanV3Op
    .Execute(new ModelBanUpdateRequest()
    {
        Enabled = false,
        SkipNotif = false
    }, banId, sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

Ban Notifications

Use the following code to implement ban notifications on the client side. Using this method, players can be told that they have been banned and the reason why.

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().UserBannedNotification += result =>
{
    Debug.Log("You have been banned. Reason: " + result.Value.reason);
};

Go Extend SDK

connMgr := &integration.ConnectionManagerImpl{}
connection, errcon := connectionutils.NewWebsocketConnection(configRepo, tokenRepo, func(dataByte []byte) {

    msg := decodeWSMessage(string(dataByte))

    if v, ok := msg["type"]; ok {
        msgType = v
    }
    switch msgType {
    case model.TypeNotificationMessage:
    }
})
if errcon != nil {
    logrus.Error(errcon)

    return
}

connMgr.Save(connection)

lobbyService := &service.LobbyServiceWebsocket{
    ConfigRepository:  configRepo,
    TokenRepository:   tokenRepo,
    ConnectionManager: connMgr,
}
err := lobbyService.UserBannedNotification()
if err != nil {
    logrus.Error(err)

    return
}

Python Extend SDK

import accelbyte_py_sdk.api.lobby.wss_models import lobby_wss_models

async def on_receive(message: str):
    wsm, error = lobby_wss_models.parse_wsm(message)
    if not error:
        if wsm.get_type() == "userBannedNotification":
            print(f"You have been banned.")

# ws_client = WebsocketsWSClient(...)

ws_client.listeners.append(on_receive)

await ws_client.connect()

# do something

await ws_client.disconnect()

Refer to Manually connect to the Lobby on how to connect to lobby using Python Extend SDK.