Best practices for banning user privileges

This page introduces using channel management RESTful APIs to ban user privileges, including overall principles, scenario recommendations, and best practices for handling exceptions.

Overall principles

Take the following principles into consideration when using the RESTful APIs:

1. Prevent your main business processes from strong reliance on the RESTful APIs.
2. Integrate the RESTful APIs prudently to avoid the impact of API request failure on your main business processes.

Recommended scenarios

Using the RESTful APIs to ban user privileges is recommended for the following scenarios.

Ban an illegal user by user ID

Methods

Ban the user's privilege to join channels by user ID. To do this, set privileges as join_channel, provide uid, leave cname and ip empty, and set time as any value other than 0.

Use case

When you find illegal users and you cannot completely ban them with your signaling system, you can call the RESTful APIs to prevent them from entering any channel.

Consideration

When you cannot completely ban illegal users with your signaling system, the RESTful APIs can be an alternative method. However, you need to consider demands for lifting the ban. Generally, you should not integrate the logic of lifting bans into your main business processes; otherwise, failure to lift bans can impact your business processes.

• The correct way to lift a ban is to do so when the banned user makes a request to lift the ban.
• Automatically lifting a ban when the banned user joins a channel is not recommended, because the user cannot join any channels if the API call to lift the ban fails.

Ban a user's privilege to publish video or audio streams

Methods

Ban the user's privilege to publish video or audio streams by user ID. To do this, set privileges as publish_audio or publish_video, provide uid, leave cname and ip empty, and set time as any value other than 0.

Use case

When you find a user who has switched roles to audience member or who does not have the required privilege and yet can still publish video or audio streams, you can call the RESTful APIs to prevent them from publishing the streams.

Consideration

• It can be risky to use the RESTful APIs to ban the user's privilege to publish video or audio streams. Use it as an alternative when your signaling system fails to notify the user to switch roles to audience member and this causes impact on your business processes.
• Consider the impact of delay or failure of API calls on publishing the streams when the user wants to switch roles to host and you need to lift the ban.
• Set the duration of the ban to be as short as possible.

• If the channel is not going to be reused, you can set a reasonable duration for the ban to prevent users from rejoining this channel after it is dismissed.
• If the channel is going to be reused on a specific date, ensure you set time as a suitable value so that the ban is lifted before that date. Avoid setting a long ban duration or lifting the ban until the channel is reused. If the API request fails, users cannot join the channel.
• If the channel is going to be reused, but the date is not known, Agora recommends that you set time as 1, or use Kick users from a channel instead.

Ban illegal users by IP address

Methods

Ban users' privilege to join the channel by IP. To do this, set privileges as join_channel, provide ip, leave cname and uid empty, and set time as any value other than 0.

Use case

If your business process is attacked and you identify the illegal IP, you can ban the IP with ip.

Consideration

Using IP to ban users can impact innocent users in some cases, such as when multiple users share the same IP.

Unsuitable scenarios

Using the RESTful APIs to ban user privileges is not recommended for the following scenarios.

Using RESTful APIs to control privilege by role

Agora does not recommend that you ban a user's privilege to publish streams when they switch their role to audience member and lift the ban when they switch their role to host. This leads RTC services to rely on the RESTful APIs, and if the API requests for listing bans fail, the user cannot publish streams.

Using RESTful APIs to manage user privileges to join the channel

Agora does not recommend that you ban the user's privilege to join the channel when the user leaves the channel and lift the ban when the user rejoins the channel. This leads RTC services to rely on the RESTful APIs, and if the API requests for listing bans fail, the user cannot rejoin the channel. Agora recommends that you use Kick users from a channel.

Best practices for handling API call exceptions

Timeout settings

To respond to unstable internet connection, Agora recommends that you set the request timeout for client as 20 seconds or more (and not less than 5 seconds). For the retry requests, set the timeout as long as necessary to increase the request success rate under an unstable internet connection.

Retry request settings

You can decide whether you need retry requests and the maximum time of retry requests based on your business logic.

If the request returns an error code greater than or equal to 500 or the request times out, you can retry the RESTful API request with incremental intervals between retry requests.