Commit d2889ca6 authored by Daniel Gultsch's avatar Daniel Gultsch
Browse files

document /password api

parent 5055890d
......@@ -31,4 +31,27 @@ Requests an SMS containing a 6 digit code to be send to `$phoneNumber`. The numb
### `POST /password`
Sets a new password for a user as generated by the app. Depending on whether or not the user existed beforehand it will either create a new user or change the password for the existing user. If the preexisting user hasn’t logged in for more than 28 days the old account will be deleted and a new account will be created. (As QuicksyServer assumes the phone number might have been reassigned.)
The password will be transmitted in the body of the POST. Phone number and 6 digit code (received via SMS) will be used as username and password for HTTP Basic Auth.
#### Request Header
* `Authorization`: HTTP Basic auth with username = phone number as E.164 string and password = 6 digit pin.
* `User-Agent`: Formatted to `Name/Version` with version being formatted according to [Sementic Versioning](
#### Response codes
* `200`: Account has been created or password has been changed
* `401`: Incorrect pin code. Displayed to user as: **The pin you have entered is incorrect.**
* `403`: Outdated app version (as reported by *User-Agent*). Displays to user as: **You are using an out of date version of this app.**
* `404`: Unable to find pin code for phone number (probably because it has been expired.). Displayed to user as: **The pin we have sent you has expired.**
* `429`: Rate limited. Too many attempts to enter pin. Displayed to user as: **Too many attempts**
* `500`: Internal Server Error. Unable to reach the database, the XMPP server or the SMS verification provider. Displays to user as: **Something went wrong processing your request.**
* `501`, `502`, `503`: Temporary errors. Usually not throwns by QuicksyServer but by reverse proxy in front of it. Displays to user as: **Temporarily unavailable. Try again later.** Note: Not to be used for rate limiting.
#### Response Header
* `Retry-After`: Time in seconds after which the client can make another attempt. Parsed in combination with response code `429`.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment