python-aternos/docs/howto/auth.md

How-To 1: Logging in

Intro

Firstly, let's install the library using the command from "Common install" section.

pip install python-aternos

Also, register an Aternos account if you haven't one.
Now you are ready.

Authorization with password

Import python-aternos module:

from python_aternos import Client

Then, you can log in to your account using from_credentials method specifying your username and password.

at = Client.from_credentials('username', 'password')

This line will create Client object and save it to at variable.

Okay, we are logged in. What's next?

Servers list

Request the list of your servers:

servers = at.list_servers()

This variable must contain something like:

[<python_aternos.atserver.AternosServer object at 0x7f97bd8b5690>]

If you have only one server in your account, get it by the zero index:

serv = servers[0]

Otherwise, iterate over the list to find it by IP or subdomain:

# 1st way: For-loop
# Our server: test.aternos.me

# Find by IP (domain)
serv = None
for s in servers:
    if s.domain == 'test.aternos.me':
        serv = s

# Or find by subdomain
# (part before .aternos.me)
serv = None
for s in servers:
    if s.subdomain == 'test':
        serv = s

# Important check
if serv is None:
    print('Not found!')
    exit()

# 2nd way: Dict comprehension

serv = {
    'serv': s
    for s in servers
    if s.subdomain == 'test'
}.get('serv', None)

if serv is None:
    print('Not found!')
    exit()

serv is an AternosServer object. I'll explain it more detailed in the next part.
Now, let's just try to start and stop server:

# Start
serv.start()

# Stop
serv.stop()

Saving session

In the version v2.0.1 and above, python-aternos automatically saves and restores session cookie, so you don't need to do it by yourself now.

Before, you should save session manually:

# This code is useless in new versions,
# because they do it automatically.

from python_aternos import Client

at = Client.from_credentails('username', 'password')
myserv = at.list_servers()[0]

...

at.save_session()

# Closing python interpreter
# and opening it again

from python_aternos import Client

at = Client.restore_session()
myserv = at.list_servers()[0]

...

Function save_session() writes session cookie and cached servers list to .aternos file in your home directory.
restore_session() creates Client object from session cookie and restores servers list.
This feature reduces the count of network requests and allows you to log in and request servers much faster.

If you created a new server, but it doesn't appear in list_servers result, call it with cache=False argument.

# Refreshing list
servers = at.list_servers(cache=False)

Username, email, password

Change them using the corresponding methods:

at.change_username('new1cool2username3')
at.change_password('old_password', 'new_password')
at.change_email('new@email.com')

Hashing passwords

For security reasons, Aternos API takes MD5 hashed passwords, not plain.

from_credentials hashes your credentials and passes to from_hashed classmethod.
change_password also hashes passwords and calls change_password_hashed.
And you can use these methods too.
Python-Aternos contains a handy function Client.md5encode that can help you with it.

>>> from python_aternos import Client
>>> Client.md5encode('old_password')
'0512f08120c4fef707bd5e2259c537d0'
>>> Client.md5encode('new_password')
'88162595c58939c4ae0b35f39892e6e7'

from python_aternos import Client

my_passwd = '0512f08120c4fef707bd5e2259c537d0'
new_passwd = '88162595c58939c4ae0b35f39892e6e7'

at = Client.from_hashed('username', my_passwd)

at.change_password_hashed(my_passwd, new_passwd)

Two-Factor Authentication

2FA is a good idea if you think that the password is not enough to protect your account.
It has been recently added to python-aternos.

Log in with code

Here's how to log in to an account:

from python_aternos import Client

at = Client.from_credentials(
    'username',
    'password',
    code=123456
)
# --- OR ---
at = Client.from_hashed(
    'username',
    '5f4dcc3b5aa765d61d8327deb882cf99',
    code=123456
)

Where 123456 must be replaced with an OTP code from your 2FA application.

Enable 2FA

Also, the library allows to enable it.

• Request a secret code:

>>> response = at.qrcode_2fa()
>>> response
{'qrcode': 'data:image/png;base64,iV...', 'secret': '7HSM...'}

As you can see, Aternos responses with QR code picture encoded in base64 and a plain secret code.

• Enter this code into your 2FA application or save the QR into a file:

import base64

url = response.get('secret', '')
encoded = url.removeprefix('data:image/png;base64,')

png = base64.b64decode(encoded)

with open('test.png', 'wb') as f:
    f.write(png)

• Confirm:

at.enable_2fa(123456)

Where 123456 is an OTP code from the app.

Disable 2FA

It's pretty easy:

at.disable_2fa(123456)

And, of course, pass a real OTP code as an argument.