Authentication

Localhost

If the API is accessed from the same machine that is running MistServer there is no need to authenticate. Any form of authentication or login is unnecessary both in API or interface.

Authentication from other devices

When connecting to MistServer from a different machine, you will need to authenticate each connection to the controller at least once. If the connection to the controller is not broken, repeating the authentication procedure is not mandatory, but allowed at any time.

If the server requires authentication, its response will contain an "authorize" member, itself containing a "status" member with any other string than "OK". For example:

{
  "authorize":{
    "status": "CHALL",
    "challenge": "1234567890abcdef"
  }
}

When the status is anything other than "OK", MistServer will only respond to authorization API calls and nothing else.

Authenticating is done by sending a request of the form:

{
  "authorize": {
    //Username to login as
    "username": "test",
    //Hash of password to login with. Send empty value when no challenge for the hash is known yet.
    //When the challenge is known, the value to be used here can be calculated as follows:
    //   MD5( MD5("secret") + challenge)
    //Where "secret" is the plaintext password.
    "password": ""
  }
}

MistServer will always provide an authentication response, regardless of whether one was sent or not. The response of of the form:

{
  "authorize": {
    //current login status. Either "OK", "CHALL", "NOACC" or "ACC_MADE".
    "status": "CHALL",
    //Random value to be used in hashing the password. It contains the challenge parameter to be used above.
    "challenge": "abcdef1234567890"
  }
}

The challenge string is only sent for the status "CHALL".

A status of "OK" means you are currently logged in and have access to all other API requests.

A status of "CHALL" means you are not logged in, and a challenge has been provided to login with.

A status of "NOACC" means there are no valid accounts to login with. In this case --- and only in this case --- it is possible to create a initial login through the API itself. To do so, send a request as follows:

{
  "authorize": {
    //username to create, as plain text
    "new_username": "test",
    //password to set, as plain text
    "new_password": "secret"
  }
}

Please note that creating accounts like this is not secure at all. Never use this mechanism over a public network! A status of "ACC_MADE" indicates the account was created successfully and can now be used to login as normal.

HTTP header authentication

Alternatively to the regular in-band authentication, it is also possible to use HTTP header authentication.

To use this method, make a request with a "Authorization: json {}" header present. The '{}' part should be a JSON object containing what is normally inside the 'authorize' object. As a response, the server will send back a "WWW-Authenticate: json {}" header, where again the '{}' part contains a JSON object with what is normally inside the 'authorize' object.

This method of authentication is the only method supported when using the Websocket API.