diff --git a/docs/reference/api/docker_remote_api.md b/docs/reference/api/docker_remote_api.md
index 75edd928bf..5aee96c53a 100644
--- a/docs/reference/api/docker_remote_api.md
+++ b/docs/reference/api/docker_remote_api.md
@@ -125,6 +125,7 @@ This section lists each version from latest to oldest.  Each listing includes a
 * `GET /info` now returns `KernelMemory` field, showing if "kernel memory limit" is supported.
 * `POST /containers/create` now takes `PidsLimit` field, if the kernel is >= 4.3 and the pids cgroup is supported.
 * `GET /containers/(id or name)/stats` now returns `pids_stats`, if the kernel is >= 4.3 and the pids cgroup is supported.
+* `POST /auth` now returns an `IdentityToken` when supported by a registry.
 
 ### v1.22 API changes
 
diff --git a/docs/reference/api/docker_remote_api_v1.23.md b/docs/reference/api/docker_remote_api_v1.23.md
index c2902dac06..c9cbf859ff 100644
--- a/docs/reference/api/docker_remote_api_v1.23.md
+++ b/docs/reference/api/docker_remote_api_v1.23.md
@@ -1957,11 +1957,11 @@ Request Headers:
     }
         ```
 
-    - Token based login:
+    - Identity token based login:
 
         ```
     {
-            "registrytoken": "9cbaf023786cd7..."
+            "identitytoken": "9cbaf023786cd7..."
     }
         ```
 
@@ -2091,7 +2091,8 @@ Status Codes:
 
 `POST /auth`
 
-Get the default username and email
+Validate credentials for a registry and get identity token,
+if available, for accessing the registry without password.
 
 **Example request**:
 
@@ -2099,9 +2100,8 @@ Get the default username and email
     Content-Type: application/json
 
     {
-         "username":" hannibal",
-         "password: "xxxx",
-         "email": "hannibal@a-team.com",
+         "username": "hannibal",
+         "password": "xxxx",
          "serveraddress": "https://index.docker.io/v1/"
     }
 
@@ -2109,6 +2109,11 @@ Get the default username and email
 
     HTTP/1.1 200 OK
 
+    {
+         "Status": "Login Succeeded",
+         "IdentityToken": "9cbaf023786cd7..."
+    }
+
 Status Codes:
 
 -   **200** – no error