IP Bans & Whitelist¶

IP Ban Management¶

ban_ip(ip_address, duration_seconds=None)¶

Ban an IP address.

# Ban for 1 hour
ban = admin.ban_ip("192.168.1.100", duration_seconds=3600)
print(ban.banned_until)
print(ban.remaining_seconds)

# Ban with the server's default duration
ban = admin.ban_ip("192.168.1.100")

Returns: IPBanStatusResponse — see Access List Models.

Raises: ValidationError (invalid IP address), AuthenticationError.

unban_ip(ip_address)¶

Unban an IP address.

result = admin.unban_ip("192.168.1.100")
if result.was_banned:
    print(f"Unbanned {result.ip_address}")
else:
    print(f"{result.ip_address} was not banned")

Returns: IPUnbanResponse.

Raises: AuthenticationError.

get_ban_status(ip_address)¶

Check whether an IP is currently banned.

status = admin.get_ban_status("192.168.1.100")
if status.is_banned:
    print(f"Banned until: {status.banned_until}")
    print(f"Remaining: {status.remaining_seconds}s")
else:
    print("Not banned")

Returns: IPBanStatusResponse.

Raises: AuthenticationError.

get_ban_list()¶

Get all currently banned IPs.

bans = admin.get_ban_list()
print(f"Total bans: {bans.total}")
for ban in bans.entries:
    print(f"  {ban.ip_address} until {ban.banned_until}")

Returns: IPBanListResponse.

Raises: AuthenticationError.

Whitelist Management¶

add_to_whitelist(ip_address, description=None)¶

Add an IP address or CIDR range to the whitelist.

result = admin.add_to_whitelist("10.0.0.0/24", description="Office network")
print(result.message)

Returns: WhitelistAddResponse.

Raises: ValidationError (invalid IP address/CIDR), AuthenticationError.

remove_from_whitelist(ip_address)¶

Remove an IP address from the whitelist.

result = admin.remove_from_whitelist("10.0.0.0/24")
if result.was_whitelisted:
    print(f"Removed {result.ip_address} from whitelist")
else:
    print(f"{result.ip_address} was not whitelisted")

Returns: WhitelistRemoveResponse.

Raises: AuthenticationError.

list_whitelist()¶

Get all whitelisted IPs.

whitelist = admin.list_whitelist()
print(f"Total entries: {whitelist.total}")
for entry in whitelist.entries:
    print(f"  {entry.ip_address}: {entry.description}")
    print(f"    Added: {entry.added_at}")

Returns: WhitelistListResponse.

Raises: AuthenticationError.

Access List Models¶

IPBanRequest¶

IPUnbanRequest¶

IPUnbanResponse¶

IPBanStatusResponse¶

Returned by both ban_ip() and get_ban_status().

IPBanEntry¶

IPBanListResponse¶

WhitelistAddRequest¶

WhitelistAddResponse¶

WhitelistRemoveRequest¶

WhitelistRemoveResponse¶

WhitelistEntry¶

WhitelistListResponse¶

Related¶

• v2hub-cli IP Ban Management / Whitelist Management — the CLI wrapper around this API, including tab-completion of banned/whitelisted IPs.