Skip to Content
Authgate 1.9.3 is released 🎉
FeaturesBan System

Ban System

The Ban System helps you protect your application by blocking access from unwanted users, IP addresses, hardware IDs, or licenses. When you ban someone, they are immediately locked out and cannot access your application anymore.

What Can Be Banned?

Authgate supports four types of bans:

  • Users - Block a specific user account
  • IP Addresses - Block requests from a specific IP address
  • Hardware IDs - Block a specific device (computer/machine)
  • Licenses - Block a specific license key

How Banning Works

Banning a User

When you ban a user from your admin panel:

  1. The user is immediately logged out from all devices
  2. All their active sessions are terminated
  3. Their IP addresses and hardware IDs are automatically banned too (cross-banning)
  4. They cannot log in again until unbanned

This comprehensive approach prevents the banned user from simply logging in from a different device or network.

Automatic Cross-Banning

Authgate includes intelligent automatic protection that prevents banned entities from circumventing restrictions. The system continuously monitors for banned identifiers and automatically creates new bans when needed.

When Cross-Banning Happens

Authgate automatically checks for bans and triggers cross-bans during these operations:

1. Sign Up (Username/Password)

  • Checks: IP address, Hardware ID
  • If either is banned → blocks signup and bans the other identifier

2. Sign Up with License Code

  • Checks: IP address, Hardware ID, License
  • If any is banned → blocks signup and bans all other identifiers

3. Login

  • Checks: IP address, Hardware ID, User account
  • If any is banned → blocks login and bans all other identifiers

4. Every API Request (authenticated users)

  • Checks: IP address, User account
  • If either is banned → blocks request and bans the other identifier

5. License Activation

  • Checks: IP address, User account, License
  • If any is banned → blocks activation and bans all other identifiers

6. Anonymous Requests (if anonymous access is enabled)

  • Checks: IP address only
  • If banned → blocks request

How Cross-Banning Works

When a banned identifier is detected:

  1. The request is rejected with a 403 error
  2. All other identifiers in the request are banned
  3. All active sessions for the user are terminated
  4. The system records why the ban was created (e.g., “Used together with banned user 123”)
  5. Each ban decision is logged with “System” as the creator

Example: If you ban a user account, and they try to create a new account from a different IP address but the same hardware ID:

  • The system detects the banned hardware ID during signup
  • The signup is blocked
  • Their new IP address is automatically banned
  • The ban reason shows: “Used together with banned hardware ID abc123 (during signup)”

This creates a protective web that makes it difficult for banned entities to regain access.

What Happens When Banned?

When a banned entity tries to access your application:

  • Sign up attempts are blocked before account creation
  • Login attempts are rejected with a “banned” error
  • Active sessions are immediately revoked
  • API requests return a 403 Forbidden error with error code BANNED
  • Your users see a clear message that access is denied

Managing Bans

Admin vs System Bans

Bans in Authgate are created by two different sources:

  • Admin Bans - Created manually by you through the admin panel
  • System Bans - Created automatically during cross-banning when a banned identifier is detected

Both types work identically and can be unbanned or reported the same way. The “Decided By” field in the ban history shows who created each ban decision.

Creating a Ban (Admin)

From the Users page:

  1. Navigate to the user’s detail page
  2. Click the “Ban” action
  3. Optionally provide a reason (e.g., “Spam”, “Abuse”, “Fraud”)
  4. Confirm the ban

When you ban a user, Authgate automatically:

  • Terminates all their active sessions
  • Bans all their known IP addresses
  • Bans all their known hardware IDs

Creating IP/Hardware ID bans:

  1. Go to the Bans page in your admin panel
  2. Click “Create Ban”
  3. Select the ban type (IP Address or Hardware ID)
  4. Enter the identifier to ban
  5. Optionally provide a reason
  6. Confirm the ban

Unbanning

You can reverse a ban at any time:

  1. Go to the Bans page
  2. Find the ban you want to remove
  3. Click “Unban”
  4. Optionally provide a reason (e.g., “Appeal accepted”, “Mistake”)
  5. Confirm the unban

The entity will immediately regain access to your application.

Reporting a Ban

The “report” action serves two purposes:

  1. Re-ban an unbanned entity - If you previously unbanned someone but need to ban them again, reporting will reactivate the ban
  2. Track repeated violations - For active bans, reporting adds another entry to the ban history when you notice new violation attempts

This helps you maintain a complete record of all violations and repeated offense attempts.

Ban History

Each ban maintains a complete history of all decisions:

  • When it was created
  • Who created it (Admin or System)
  • The reason provided
  • Any unban/re-ban actions
  • Timestamps for all changes

This audit trail helps you understand the context behind each ban and track patterns of abuse.

Integration

When a banned entity tries to access your application, Authgate automatically returns a 403 error with error code BANNED.

Your application can catch this error and display an appropriate message to the user.

Last updated on
FilesToken Auth