Services

airvpn.web.services

APIKey

An AirVPN API key belonging to the authenticated user.

Constructed from the key entries returned by the APIManager manifest.

Attributes:

Name	Type	Description
id	str | None	Unique identifier of the key.
color	str | None	CSS color assigned to the key for display purposes, as an HSL string (e.g. "hsl(68,80%,87.5%)").
name	str | None	Display name of the key.
secret_short	str | None	Truncated/masked preview of the key's secret, safe for display.
secret	str | None	The key's full secret value.
creation_date	datetime	UTC timestamp of when the key was created, converted from the manifest's Unix timestamp.

APIManager

Bases: ClientService

Manages the authenticated user's AirVPN API keys.

Wraps the AJAX endpoints behind https://airvpn.org/apisettings/ to list, add, rename, and delete API keys.

Attributes:

Name	Type	Description
keys	list[APIKey]	All API keys currently owned by the user.

add() -> APIKey

Create a new API key.

The "add" action doesn't return the new key's data, so update is called afterward to refresh keys with the newly created key.

Returns:

Name	Type	Description
APIKey	APIKey	The most recently added api key.

delete(key: APIKey | str)

Delete an existing API key.

Parameters:

Name	Type	Description	Default
key	APIKey | str	APIKey instance or key ID to delete.	required

Raises:

Type	Description
InvalidAPIKey	If key is a string ID that doesn't match any known key.

edit(key: APIKey | str, name: str)

Rename an existing API key.

Parameters:

Name	Type	Description	Default
key	APIKey | str	APIKey instance or key ID to edit.	required
name	str	New name to set for the key.	required

Raises:

Type	Description
InvalidAPIKey	If key is a string ID that doesn't match any known key.

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

update(data=None)

Refresh keys from the server manifest.

Fetches the current manifest and repopulates keys and the internal key lookup map from the response.

ClientService

Base class for AJAX-based clients against an AirVPN endpoint.

Provides shared CSRF-token handling and a generic AJAX request/edit interface that endpoint-specific managers (like PortManager or APIManager) can build on.

Attributes:

Name	Type	Description
session	WebSession	The authenticated web session used for all requests made by this service.
ecsrf	str | None	CSRF token scraped from the endpoint's page, used to authorize AJAX requests. Lazily fetched on first use.
endpoint	str	URL of the AirVPN page this service issues AJAX requests against.

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

Conversation

Represents a messenger conversation (thread) with one or more participants.

Attributes:

Name	Type	Description
owner_id	int	The user ID of the conversation owner (the authenticated user).
session	WebSession	The active web session used for requests.
title	str	The conversation's title/subject.
body	str	A snippet/preview of the conversation's body content.
id	int	The unique ID of the conversation.
messages	list[Message]	The messages belonging to this conversation, fetched on first access.

update(page=1)

Fetch and parse the conversation's messages from the given page, replacing the cached message list.

Parameters:

Name	Type	Description	Default
page	int	The page number of messages to retrieve. Defaults to 1.	1

Current

The user's currently active custom DNS configuration.

Attributes:

Name	Type	Description
lists	list[str]	Codes of the DNS lists currently selected.
enabled	bool	Whether custom DNS is currently enabled.

DeviceKey

A device associated with the user's account.

Represents an entry from the keys section of the PortManager manifest. Despite the name, these correspond to the user's devices rather than cryptographic keys.

Attributes:

Name	Type	Description
name	str	Display name of the device.
id	str	Unique identifier of the device.
description	str | None	Optional free-text description of the device.
color	str	Color label/tag associated with the device.
version	str	Version string of the device's client software.
renew_first_date	int	Timestamp of the device's first renewal.
renew_last_date	int	Timestamp of the device's most recent renewal.
renew_counter	int	Number of times the device has been renewed.
wg_public_key	str	WireGuard public key for the device.
wg_ipv4	str	WireGuard IPv4 address assigned to the device.
wg_ipv6	str	WireGuard IPv6 address assigned to the device.
show_dns	bool	Whether DNS info is shown for the device.
vpn_last_from_date	str	Start date of the device's last VPN session.
vpn_last_to_date	str	End date of the device's last VPN session.
vpn_attempt_date	str	Date of the device's last connection attempt.
vpn_attempt_message	str	Message/status from the last connection attempt.
deprecated	bool	Whether the device is deprecated. Defaults to False.
pending	str	Pending action or status for the device, if any.

DeviceManager

Bases: ClientService

Manages the authenticated user's registered devices.

Wraps the AJAX endpoints behind https://airvpn.org/devices/ to list, edit, renew, and delete the user's devices.

Attributes:

Name	Type	Description
total_deprecated	int	Number of deprecated devices on the account.
devices	list[DeviceKey]	All devices currently registered to the account.

add() -> DeviceKey

Register a new device and refresh devices once it appears.

Returns:

Name	Type	Description
DeviceKey	DeviceKey	The newly added device.

delete(device: DeviceKey | str)

Delete an existing device.

Parameters:

Name	Type	Description	Default
device	DeviceKey | str	DeviceKey instance or device ID to delete.	required

edit(device: DeviceKey | str, name: str | None = None, description: str | None = None)

Edit a device's name and/or description.

Parameters:

Name	Type	Description	Default
device	DeviceKey | str	DeviceKey instance or device ID to edit.	required
name	str | None	New name to set for the device, if any.	None
description	str | None	New description to set for the device, if any.	None

Raises:

Type	Description
ValidationError	If neither name nor description is provided.

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

get(device: DeviceKey | str)

Resolve a device to a DeviceKey instance.

Parameters:

Name	Type	Description	Default
device	DeviceKey | str	DeviceKey instance or device ID to resolve.	required

Returns:

Type	Description
	The matching DeviceKey instance.

Raises:

Type	Description
ValidationError	If device is a string ID that doesn't match any known device.

poll_update(check_callback: Callable[[list[DeviceKeyDict]], bool])

Poll the server until a condition is met, then refresh devices.

Repeatedly fetches the device manifest, sleeping one second between attempts, until check_callback returns False for the current set of keys, then applies the final result via update.

Parameters:

Name	Type	Description	Default
check_callback	Callable[[list[DeviceKeyDict]], bool]	Called with the current list of raw key data on each poll; polling continues while it returns True.	required

renew(device: DeviceKey | str)

Renew an existing device.

Parameters:

Name	Type	Description	Default
device	DeviceKey | str	DeviceKey instance or device ID to renew.	required

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

update(data=None)

Refresh devices and total_deprecated from the server.

Parameters:

Name	Type	Description	Default
data		Pre-fetched manifest data to use instead of making a new request. If falsy, the manifest is fetched from the server.	None

DnsList

A DNS list available from AirVPN.

Attributes:

Name	Type	Description
code	str	Unique code identifying the DNS list.
name	str	Display name of the DNS list.
description	str | None	Optional free-text description of the list.
home	str	Homepage URL associated with the list.
experimental	bool	Whether the list is marked experimental.
nitems	int	Number of entries contained in the list.
last_update	datetime	UTC timestamp of when the list was last updated.

DnsManager

Bases: ClientService

Manages the authenticated user's custom DNS configuration.

Wraps the AJAX endpoints behind https://airvpn.org/dns/ to view available DNS lists and toggle or edit the user's custom DNS selection.

Attributes:

Name	Type	Description
lists	list[Dns]	All DNS lists currently available.
current	Current	The user's currently active DNS configuration.
device	str | None	The device this configuration applies to, if any.

add_answer(host: str, type: AnswerType = AnswerType.EXACT, action: ActionType = ActionType.DENY, records: list[Record] | None = None) -> Answer

Create a new answer rule and add it to the current configuration.

Parameters:

Name	Type	Description	Default
host	str	The hostname or pattern the rule matches against.	required
type	AnswerType	How host is matched (e.g. exact, wildcard). Defaults to AnswerType.EXACT.	EXACT
action	ActionType	The action to take when the rule matches (e.g. allow, deny). Defaults to ActionType.DENY.	DENY
records	list[Record] | None	Initial list of Record instances to attach to the answer. Defaults to an empty list.	None

Returns:

Type	Description
Answer	The newly created Answer.

add_list(dns: DnsList | list[DnsList] | list[str] | str)

Add one or more DNS lists to the current configuration.

Parameters:

Name	Type	Description	Default
dns	DnsList | list[DnsList] | list[str] | str	A Dns instance, DNS list code, or a list of either, to add to the current selection.	required

add_record(answer: Answer, type: RecordType, value: str) -> Record

Create a record, attach it to an answer, and save the change.

Parameters:

Name	Type	Description	Default
answer	Answer	The Answer instance to attach the new record to.	required
type	RecordType	The RecordType of the record to create (e.g. A, AAAA, CNAME).	required
value	str	The record's value (e.g. an IP address or hostname).	required

Returns:

Type	Description
Record	The Answer the record was added to.

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

from_dns(session: WebSession, device: str) classmethod

Create a DnsManager scoped to a specific device.

Parameters:

Name	Type	Description	Default
session	WebSession	The WebSession to use for requests.	required
device	str	The device identifier to scope the configuration to.	required

Returns:

Type	Description
	A new DnsManager instance for the given device.

get_list(dns: DnsList | str)

Resolve a DNS list to a Dns instance.

Parameters:

Name	Type	Description	Default
dns	DnsList | str	Dns instance or DNS list code to resolve.	required

Returns:

Type	Description
	The matching Dns instance.

Raises:

Type	Description
ValidationError	If dns is a string code that doesn't match any known DNS list.

remove_answer(answer: Answer)

Remove an answer from the current DNS configuration and save the change.

Parameters:

Name	Type	Description	Default
answer	Answer	The Answer instance to remove.	required

Raises:

Type	Description
ValueError	If answer is not present in self.current.answers.

remove_list(dns: DnsList)

Remove a DNS list from the current configuration and save the change.

Parameters:

Name	Type	Description	Default
dns	DnsList	The DNS list code (str) to remove from the current selection.	required

Raises:

Type	Description
ValueError	If dns is not present in self.current.lists.

remove_record(answer: Answer, record: Record)

Remove a record from an answer's record list and save the change.

Parameters:

Name	Type	Description	Default
answer	Answer	The Answer instance containing the record.	required
record	Record	The Record instance to remove.	required

Raises:

Type	Description
ValueError	If record is not present in answer.records.

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

save()

Persist the current DNS configuration to the server.

toggle()

Toggle custom DNS on or off and save the change.

update()

Refresh lists and current from the server.

Fetches the DNS page and parses the embedded JSON data to repopulate lists, the internal DNS lookup map, current, and device.

InboxManager

Manages the authenticated user's messenger inbox and conversations.

Attributes:

Name	Type	Description
session	WebSession	The active web session used for requests.
owner_id	int	The user ID of the authenticated user (inbox owner).
conversations	list[Conversation]	The list of conversations in the inbox.

start_conversation(user: WebUser | str, subject: str, body: str) -> Conversation

Create a conversation with a user.

Parameters:

Name	Type	Description	Default
username	str	The username of the recipient.	required
subject	str	The subject of the message.	required
body	str	The body content of the message.	required

Returns:

Type	Description
Conversation	Conversation | None: returns the created conversation.

update()

Fetch and parse the list of conversations from the messenger inbox page, appending any found conversations to self.conversations.

InvalidAPIKey

Bases: AirVPNException

Raised when the API key specified doesn't exist

InvalidPort

Bases: AirVPNException

Raised when the port requested isn't available.

Message

Represents a single message within a conversation.

Attributes:

Name	Type	Description
conversation	Conversation	The conversation this message belongs to.
session	WebSession	The active web session used for requests.
user	WebUser	The user who sent the message.
content	str	The stripped content of the message.
timestamp	datetime	UTC datetime of when the message was sent.
id	int	The unique ID of the message (comment ID).

edit(content: str)

Edit this message's content.

Parameters:

Name	Type	Description	Default
content	str	The new content to replace the existing message body.	required

Raises:

Type	Description
ValidationError	If the current user is not the owner of the message/conversation.

Port

A single forwarded port owned by the authenticated user.

Constructed from the port entries returned by the PortManager manifest, and from the responses of port-mutating actions like PortManager.open.

Attributes:

Name	Type	Description
port	int | None	The forwarded port number.
pool	int | None	Identifier of the pool the port belongs to.
notes	str | None	Free-text note/description attached to the port.
device	str | None	Name of the device associated with the port.
enabled	bool | None	Whether the port is currently enabled.
protocol	Literal['both', 'tcp', 'udp'] | None	Protocol restriction for the port.
iplayer	Literal['both', 'v6', 'v4'] | None	IP layer restriction for the port.
local	int | None	Local port the forwarded port maps to.
dns	str | None	Dynamic DNS hostname associated with the port.

PortManager

Bases: ClientService

Manages the authenticated user's forwarded ports on AirVPN.

Wraps the AJAX endpoints behind https://airvpn.org/ports/ to list, open, close, and edit forwarded ports, as well as inspect active sessions on a port. Any mutating action (open, close, edit) triggers a poll loop afterward, since AirVPN applies these changes asynchronously on the server side.

Attributes:

Name	Type	Description
session	WebSession	The authenticated web session used for all requests made by this manager.
ecsrf	str | None	CSRF token scraped from the ports page, used to authorize AJAX requests. Lazily fetched on first use.
pool	str | None	Identifier of the port pool the user belongs to, as reported by the manifest.
ports	list[Port]	All ports currently owned by the user.
keys	list[Key]	Keys associated with the user's ports, as reported by the manifest.

check_propagation(ddns_name: str, services=['airvpn', 'dnsadvantage', 'cloudflare', 'google', 'opendns'])

Check which DNS services have propagated a dynamic DNS record.

Queries each service in services for the current IPv4/IPv6 resolution of ddns_name, and collects the names of services that have already propagated the record (i.e. return a non-empty address).

Parameters:

Name	Type	Description	Default
ddns_name	str	The dynamic DNS hostname to check propagation for.	required
services		Names of DNS services to check. Defaults to ["airvpn", "dnsadvantage", "cloudflare", "google", "opendns"].	['airvpn', 'dnsadvantage', 'cloudflare', 'google', 'opendns']

Returns:

Type	Description
	list[str]: Names of the services that have propagated the record.

close(port: int | Port)

Close (delete) an existing forwarded port.

Parameters:

Name	Type	Description	Default
port	int | Port	Port number or Port instance to close.	required

Raises:

Type	Description
InvalidPort	If the given port does not exist.

edit(port: int | Port, device: str | None = None, note: str | None = None, protocol: Literal['both', 'udp', 'tcp'] | None = None, localport: int | None = None, ddns: str | None = None, layer: Literal['both', 'v6', 'v4'] | None = None)

Edit one or more attributes of an existing forwarded port.

Only fields that are not None are sent as edit requests. After submitting the requested edits, blocks until the server finishes applying them.

Parameters:

Name	Type	Description	Default
port	int | Port	Port number or Port instance to edit.	required
device	str | None	New device name to associate with the port.	None
note	str | None	New note/description for the port.	None
protocol	Literal['both', 'udp', 'tcp'] | None	New protocol restriction ("both", "udp", or "tcp").	None
localport	int | None	New local port to forward to.	None
ddns	str | None	New dynamic DNS hostname for the port.	None
layer	Literal['both', 'v6', 'v4'] | None	New IP layer restriction ("both", "v6", or "v4").	None

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

get_sessions(port: int | Port) -> list[PortSession]

Retrieve active sessions for a given port.

Parameters:

Name	Type	Description	Default
port	int | Port	Port number or Port instance to query.	required

Returns:

Type	Description
list[PortSession]	list[PortSession]: Active sessions currently using the port.

get_used_ports() -> list[int]

Retrieve the list of currently used ports in the primary pool.

Fetches usage data via the "graph" action and returns the ports from the first pool in the response.

Returns:

Type	Description
list[int]	list[int]: Port numbers currently in use in the primary pool, or an empty list if the response contains no pool data.

open(port: int | None = None) -> Port

Open (forward) a new port.

Parameters:

Name	Type	Description	Default
port	int | None	Port number to open. Must be >= 2048 and not already in use.	None

Returns:

Name	Type	Description
Port	Port	The newly created Port instance.

Raises:

Type	Description
InvalidPort	If port is below 2048, or is already in use.

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

sequential_search(amount: int) -> int

Search for a run of consecutive free ports.

Asks the server to find amount consecutive unused ports.

Parameters:

Name	Type	Description	Default
amount	int	Number of consecutive free ports to search for.	required

Returns:

Type	Description
int	The starting port number of the free run, or 0 if no such
int	run of free ports was found.

test_open(port: int | Port) -> list[str]

Test which of a port's active TCP sessions are reachable.

Fetches the sessions for port and, for each non-UDP session, issues a connectivity test against the session's server IP and port.

Parameters:

Name	Type	Description	Default
port	int | Port	Port number or Port instance to test.	required

Returns:

Type	Description
list[str]	list[Session]: The sessions that passed the connectivity test.

update()

Refresh the manager's state from the server manifest.

Fetches the current manifest and repopulates pool, ports, keys, and the internal port lookup map from the response.

PortSession

An active session using one of the user's forwarded ports.

Constructed from the session entries returned by PortManager.get_sessions, and used by PortManager.test_open to check connectivity.

Attributes:

Name	Type	Description
port	int | None	The forwarded port number the session is using.
pool	int | None	Identifier of the pool the port belongs to.
dns_name	str | None	Dynamic DNS hostname associated with the port.
notes	str | None	Free-text note/description attached to the port.
local	int | None	Local port the forwarded port maps to.
iplayer	Literal['both', 'v6', 'v4'] | None	IP layer restriction for the port.
protocol	Literal['both', 'tcp', 'udp'] | None	Protocol used by the session.
server_name	str | None	Name of the VPN server handling the session.
server_planet	str | None	Planet designation of the VPN server (AirVPN's naming scheme for servers).
server_continent	str | None	Continent the VPN server is located on.
server_location	str | None	City/location of the VPN server.
server_country	str | None	Country the VPN server is located in.
device_name	str | None	Name of the device that opened the session.
device_description	str | None	Description of the device that opened the session.
server_ip	str | None	IP address of the VPN server.
client_ip	str | None	IP address of the connecting client.

Session

An active VPN connection session for one of the user's devices.

Constructed from the session entries returned when listing a device's live connections.

Attributes:

Name	Type	Description
index	int | None	Index of the session in the response list.
session_id	str | None	Unique identifier of the session.
device_id	str | None	Identifier of the connected device.
device_name	str | None	Name of the connected device.
device_description	str | None	Description of the connected device, if set.
server_html	str | None	HTML snippet describing the connected server (e.g. name/flag markup), as returned by the server.
connected_since	datetime	UTC timestamp of when the session started, converted from the response's Unix timestamp.
bytes_write	int | None	Total bytes sent during the session.
bytes_read	int | None	Total bytes received during the session.
speed_write	int | None	Current upload speed, in bytes per second.
speed_read	int | None	Current download speed, in bytes per second.
software_name	str | None	Name of the client software used to connect.
software_img	str | None	URL or path of an icon representing the client software.
last_handshake	datetime	UTC timestamp of the most recent handshake, converted from the response's Unix timestamp string.
exit_ipv4	str | None	IPv4 address the session exits the VPN through.
exit_ipv6	str | None	IPv6 address the session exits the VPN through.
vpn_ipv4	str | None	IPv4 address assigned to the device within the VPN.
vpn_ipv6	str | None	IPv6 address assigned to the device within the VPN.
entry_layer	str | None	IP layer used to connect to the entry server.
dns_filter	str | None	Name of the DNS filtering profile applied to the session.
disconnect	int | None	Flag/timestamp indicating whether and when the session was (or will be) disconnected.

SessionManager

Bases: ClientService

Manages the authenticated user's active VPN sessions.

Wraps the AJAX endpoints behind https://airvpn.org/sessions/ to list the user's currently active sessions.

Attributes:

Name	Type	Description
sessions	list[Session]	All sessions currently active on the account.

edit_request(name, value, **kwargs)

Send a generic edit_<name> action to the endpoint.

Convenience wrapper around request for the common pattern of editing a single field by name.

Parameters:

Name	Type	Description	Default
name		Name of the field to edit; sent as the edit_{name} action.	required
value		New value to set for the field.	required
**kwargs		Additional form fields to send along with the request (e.g. an id or port identifying the target record).	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

request(action: str, is_act: bool = False, **kwargs)

Send an AJAX action request to the endpoint.

Automatically attaches the CSRF token (fetching it first if not already known) and requests an AJAX-rendered response.

Parameters:

Name	Type	Description	Default
action	str	Name of the action to perform.	required
is_act	bool	If the action param is act instead.	False
**kwargs		Additional form fields to send along with the request.	{}

Returns:

Type	Description
	The parsed JSON response from the server.

Raises:

Type	Description
APIError	If the response is a dict containing a non-None "error" field.

update()

Refresh sessions from the server manifest.

ValidationError

Bases: AirVPNException

Raised when a validation check fails.

WebSession

Wraps a requests.Session with AirVPN-specific request handling.

Handles the site's JavaScript-check redirect challenge (computing and submitting the required cookie checksum) transparently, and attaches the CSRF key to outgoing requests once available.

Attributes:

Name	Type	Description
session	Session	Underlying requests session used for all HTTP calls.
csrf	str | None	CSRF key used to authenticate requests, set after login.
anti_cache	str | None	Anti-cache token captured after login.

get_checksum(token: str) -> int

Compute the checksum required to solve AirVPN's JavaScript-check redirect challenge.

Parameters:

Name	Type	Description	Default
token	str	The raw token extracted from the challenge redirect URL's aek_id query parameter.	required

Returns:

Type	Description
int	The computed checksum value to be set as the af3 cookie.

request(method: str, url: str, **kwargs) -> requests.Response

Perform an HTTP request, transparently handling AirVPN's JavaScript-check redirect challenge if encountered.

The CSRF key (if set) is automatically added to the request's query parameters. If the response indicates the JavaScript-check challenge, this method computes the required checksum, sets it as a cookie, and retries the request against the redirect target.

Parameters:

Name	Type	Description	Default
method	str	HTTP method to use (e.g. "get", "post").	required
url	str	URL to request.	required
**kwargs		Additional keyword arguments forwarded to requests.Session.request (e.g. data, headers, params).	{}

Returns:

Type	Description
Response	requests.Response: The final response, after resolving the JavaScript-check challenge if one was encountered.

WebUser

Represents an AirVPN member's public profile.

Attributes:

Name	Type	Description
name	str	Display name of the user.
id	int	The user's ID.
image	str	URL of the user's profile image.
profile_url	str	Full URL to the user's profile page.
content_count	int | None	Number of content items (posts) the user has made.
contacts	Contacts | None	The user's contact information.
followers	int | None	Number of followers the user has.
community_reputation	int | None	The user's community reputation score.
rank	str | None	Display name of the user's rank, as shown in the profile header.
joined	datetime | None	Date and time the user joined.
last_visited	datetime | None	Date and time of the user's last visit.
about	About | None	The user's "About" information, including detailed rank data and birthday.
gender	str | None	The user's disclosed gender.
location	str | None	The user's disclosed location.
interests	str | None	The user's disclosed interests.

about property

About | None: The user's "About" information, including detailed rank data and birthday.

community_reputation property

int | None: The user's community reputation score.

contacts property

Contacts | None: The user's contact methods.

content_count property

int | None: Number of content items (posts) the user has made.

followers property

int | None: Number of followers the user has.

gender property

str | None: The user's disclosed gender.

image property

str: The user's profile picture.

interests property

str | None: The user's disclosed interests.

joined property

datetime | None: Date and time the user joined.

last_visited property

datetime | None: Date and time of the user's last visit.

location property

str | None: The user's disclosed location.

rank property

str | None: Display name of the user's rank, as shown in the profile header.

follow() -> bool

Follow this member.

Returns:

Name	Type	Description
bool	bool	True if the request succeeded.

unfollow() -> bool

Unfollow the user.

Returns:

Name	Type	Description
bool	bool	True if the request succeeded.

update()

Force update attributes.