Skip to content


Why do we need authentication?

Hoist is meant as a more of a private utility for a developer, not as a public consumer API.

A Hoist server by default comes with features that could be used as harmful by a stranger with access.


In order for a client to connect, it must authenticate itself.

By default, this is done by securely comparing the key sent by the client to the token on the server. Hoist allows you to change this behavior.

A custom login function should have a signature like this:

async def login(
    server: hoist.Server, # this is the server object
    sent_token: str, # this is the token sent by the client
) -> bool: # must return a bool, true being successful authentication

Now, you may pass it to start or serve, like so:

async def login(
    server: hoist.Server,
    sent_token: str,
) -> bool:
    token: str = server.token
    # this is the servers token, which in this case is "test"
    return sent_token == token

server = hoist.start("test", login_func=login)


Using == when comparing the servers token to the sent token is vulnerable to timing attacks. It's only used for simplicity in this example. You should something like secrets.compare_digest to handle this in a secure way.

Autogenerated Keys

So far, we've only manually defined the authentication token to log in to the server. If you don't define it yourself, Hoist does it for you.

By default, Hoist creates a 25 character secure random string.

We may change two key things in key generation: the length and the characters used.

Heres an example using both:

import hoist

choices = ["0", "1"]  # this can be any object thats indexable
# choices = "01"
# choices = ("0", "1")
server = hoist.start(default_token_len=50, default_token_choices=choices)

Hoist will then generate a key thats 50 characters long using just 0 and 1.

Hiding The Token

There might be a case where you don't want the authentication token displayed on startup. You can hide the token by passing hide_token=True:

import hoist


Now, running this will not display the token in the terminal:

startup: started server on