diff --git a/README.md b/README.md
index 4559b44293b6697b7c54bcf87826493b4b0eb0f3..47429bfb61ca66bf486d016ed5729d074355d994 100644
--- a/README.md
+++ b/README.md
@@ -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](https://semver.org/).
+
+#### 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`.
+
 ## XMPP API