micolous.id.au

portal2 has an API allowing for applications to pull some data from the portal system and interact with it. All the API calls are sent to https://authenticator.streetgeek.lan/. This document describes the protocol used by portal2 v2.8.3.

Protocols

All protocols require you use an encrypted (HTTPS) connection. Some client libraries require that you install a copy of the certificate in order to establish the connection.

As of 2.8.3, functions that attempt to get data about “you” will attempt cookie-based authentication first, and if that fails, it will attempt to identify you by your computer’s MAC address. Before 2.8.3 it would only try to authenticate you by MAC.

• HTTP GET: This API is available at /api/httpget/<encoding>/<method>/. Arguments are passed by HTTP GET queries. Specifically, these output encodings are supprted:
  • CSV (csv).
  • JSON (json): This output method has a slight quirk, all datetime objects are encoded as a floating point showing the number of seconds since the UNIX epoch (1970-01-01 00:00 UTC). While JavaScript itself has a DateTime object, JSON does not support it.
  • Pickle (pickle). This can be used to implement Python-based applications, however it is recommended you use XMLRPC instead.
  • Python (python). This is the output of the repr() function called against the result object. In Python, it is recommended that you use XMLRPC instead. New in v2.8.3.
• XMLRPC: This API is available at /api/xmlrpc/.

Structures

All of these structures are dicts (Dictionaries). So you would access them like up["first_name"] rather than using a flat array with indexes.

NetworkHost

NetworkHost represents a computer on the network. It has the following keys:

• mac_address (str): The MAC address of the system.
• ip_address (str): The current IPv4 address of the system, or False if the system is offline.
• computer_name (str): The NetBIOS name of the machine.
• first_connection (date): The date when the system first was seen by portal2.
• online (bool): Whether the system is currently online or not.
• type (str): The type of system this has been detected as. Can be one of apple, cisco, nintendo, pc, playstation or xbox. If unknown, it will return pc.

NetworkUsageDataPoint

NetworkUsageDataPoint represents usage at a point in time. Unlike other structures, this is encoded as a list (array) to save space. It has two elements:

• 0 (datetime): The date and time that this usage point was generated.
• 1 (long as str): The amount of bytes of quota used at this point.

Usage

Usage represents the amount of internet quota available to a user.

• unmetered (bool): True if the user’s quota is unmetered, False if it is metered (limited).
• used (long as str): The amount of quota used.
• available (bool): Whether there is internet quota remaining or not.
• total (long as str): The total amount of quota available to a user, in bytes, or False if unmetered.
• resets (int): The amount of times a user has had their quota reset, or False if unmetered.
• remaining (long as str): The amount of bytes remaining on the user’s quota, or False if unmetered.

UserProfile

UserProfile represents an encapsulated version of a User with the additional portal2-related profile data. It has the following keys:

• internet_on (bool): Whether or not internet access is currently enabled for the user.
• username (str): The username of the user.
• forum_uid (long as str): The forum UID of the user. It is recommended that you use this to uniquely identify users, as they may change their username. Returns 0 if the user account is not associated with a forum account. New in v2.8.3.
• first_name (str): The first name of the user. Only returned with whoami(), otherwise is an empty string, as of v2.8.2.
• last_name (str): The last name of the user. Only returned with whoami(), otherwise is an empty string, as of v2.8.2.

Methods

coffee_ip(ip)

Returns a bool indicating whether the user has paid for unlimited coffee or not and is allowed to use the coffee request system.

Returns False if the IP address is not assigned to a user, the user has been banned from using the coffee request system, or that user hasn’t paid for unlimited coffee.

Returns True if the user has paid for unlimited coffee and is allowed to use the coffee request system. Also implies the user’s coffee gland was lost in a tragic accident as a child.

There is currently no API call to indicate whether the user has paid for four cooked meals.

ping()

Always returns True. If it doesn’t, then the API is either non-functional, or it is the robot apocolypse.

usage()

Returns a Usage containing information about remaining quota for either the currently logged in, or if no user is logged in, the current IP address.

Returns False instead if:

• There was a problem finding the computer’s MAC address.
• The computer has not been “owned” by a user of portal.
• There was a problem getting user profile data.
• There is no active event.
• The user has not been signed into this event.

This function does not require a cookie to work, and does not matter whether or not you have a current session with the web interface. It also will work for hosts that have been remotely signed in.

Warning: This function does not give “live” information. It instead looks at a database of previous information so as to not create extra load on the system. This data is updated automatically every 10 minutes. Attempts to get data more frequently that would be futile, and will result in your program being blocked from using the API.

usage_history()

Returns a NetworkUsageDataPoint[] representing network usage over the last 36 hours. This can be used to graph network usage of a user over time. You should use this instead of trying to rip the graph from the web interface, so as to reduce resource usage on the server, and so you can make graphs that are native to the look and feel of your application. The data is generally presented in 10 minute intervals, however that may vary so make no assumptions.

Returns False instead if:

• There was a problem finding the computer’s MAC address.
• The computer has not been “owned” by a user of portal.
• There was a problem getting user profile data.
• There is no active event.
• The user has not been signed into this event.

This method will try to use cookie-based authentication first, and if that fails, will try to get it for the user who owns the computer at this MAC address.

Warning: This function does not give “live” information. It instead looks at a database of previous information so as to not create extra load on the system. This data is updated automatically every 10 minutes. Attempts to get data more frequently that would be futile, and will result in your program being blocked from using the API.

whatis_ip(ip)

Returns a NetworkHost containing information about the specified computer at an IPv4 address, or False if there is no online computer at that IP address.

Parameters:

1. ip (str): A dotted-quad representing the IPv4 address to look up.

Faults if the IP address specified is invalid.

whoami()

Returns a UserProfile containing information about the currently logged in user, or if no person is logged in, the person who owns this MAC address, or False if no user is logged in by either method.

This function is useful if you are running a program that interacts with portal2 on their computer, and you want to identify them.

whois_ip(ip)

Returns a UserProfile containing information about the owner of the specified computer at an IPv4 address, or False if there is no computer at that IP address, or no user is logged in.

Parameters:

1. ip (str): A dotted-quad representing the IPv4 address to look up.

Faults if the IP address specified is invalid.