Initialize a new session. This will generate a challenge and check if we require the old password hash to convert the user.

Note that an application is required to start a session and a challenge will usually time out after half a minute.

For information on how to work with sessions, refer to the documentation on using sessions.


This action requires the following tokens:

  • session-create


Required arguments are marked in bold, and optional arguments are marked in italics.

Argument Type Default Description
user String   The username for which you want to initalize a session
userip String   IP address of the user wanting to start a session


This action produces the following output on success:

An object containing the following fields:

Name Type Description
challenge String The challenge generated by the server, to be used for generating a response
salt String The salt for the user, to be used for generating a response. Will contain a fake salt when the user can not be found
needsv2hash Boolean When true, we require the API version 2 password hash to create the session


This action can return one of the default status codes, or one of the following status codes on error:

When the user entered his/her password wrong too many times in a short amount of time