Multiplayer authentication API

Category: Internal API

The multiplayer authentication API allows multiplayer servers (be they dedicated headless servers or games hosted from within a client) to verify that a connecting user is who they claim to be.

An overview of the API architecture is given in FFF-139.

All endpoints are relative to the https://auth.factorio.com/ URL.

API endpoints

/generate-server-padlock-2

Request

Query parameters

Key	Description
api_version	always set to 6 by clients

Response

JSON body

Key	Type	Description
server_padlock	string	Opaque random string, shared secret between game server and auth server
server_hash	string	Opaque game server identifier

/generate-user-server-key-2

Request

Query parameters

Key	Description
api_version	always set to 6 by clients

x-www-form-urlencoded body

Key	Description
username	The player's username, as obtained from the Web authentication API
token	User auth token, as obtained from the Web authentication API
sever_hash	Server's identifier, transmitted during connection establishment

Response

JSON body

Key	Type	Description
server_key	string	Base-64 encoded user-server-key
server_key_timestamp	string	Timestamp when server_key was issued, in YYMMDDhhmmss format

User-server-key algorithm

The game server verifies the join by calculating its own version of the user-server-key using the server_padlock, username, and server_key_timestamp. If it matches the server_key transmitted by the client, it knows that it was generated by the authentication server, attesting the validity of the user's credentials.

The algorithm is as follows:

1. Concatenate the padlock, username and timestamp strings, separated by underscores. 2. Generate an MD5 HMAC over the resulting string, with the server padlock as the key 3. Base64-encode the result

As an illustrative example, using shell commands:

$ padlock=ZjX+YSCEZgdFMVCzLLt8F8NOoWAmAG9WkUwv1dir4gg=
$ username=Xiretza
$ timestamp=240208183717

$ printf '%s_%s_%s' "$username" "$padlock" "$timestamp" | openssl mac -digest md5 -macopt "key:$padlock" -binary HMAC | base64
nV89TIBaIOvwUDQwrdK0/Q==