update challenger spec

1 files changed, 46 insertions, 11 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
index 009d2f3e..37ff3170 100644
--- a/core/api-challenger.rst
+++ b/core/api-challenger.rst
@@ -76,18 +76,56 @@ Receiving Configuration
 
     }
 
-.. _challenger-login:
+.. _challenger-setup:
 
 -----
-Login
+Setup
 -----
 
-.. http:get:: /login
+.. http:post:: /setup/$CLIENT_ID
 
+  This endpoint is used by the client to authorize the
+  execution of an address validation on its behalf.
   An ``Authorization`` header (for now always using a ``bearer`` token) should
   be included to provide the client's credentials to authorize access to the
   challenger service.  This token must match the ``client_secret`` in the
-  laster ``/auth`` request.
+  later ``/auth`` request.
+
+  **Request:**
+
+  :query client_id: Identifier of the client.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    Response is a `ChallengeSetupResponse`.
+  :http:statuscode:`403 Forbidden`:
+    The credentials of the client are invalid.
+  :http:statuscode:`404 Not found`:
+    The backup service is unaware of a matching client.
+
+  **Details::**
+
+  .. ts:def:: ChallengeSetupResponse
+
+  interface ChallengeSetupResponse {
+    // Nonce to use when constructing ``/login``
+    // endpoint.
+    nonce: string;
+  }
+
+
+.. _challenger-login:
+
+-----
+Login
+-----
+
+.. http:get:: /login/$NONCE
+.. http:post:: /login/$NONCE
+
+  This endpoint is used by the user-agent. It will
+  return a form to enter the address.
 
   **Request:**
 
@@ -103,11 +141,8 @@ Login
     The body contains a form to be submitted by the
     user-agent. The form will ask the user to specify
     their address.
-
-  :http:statuscode:`403 Forbidden`:
-    The credentials of the client are invalid.
   :http:statuscode:`404 Not found`:
-    The backup service is unaware of a matching client.
+    The backup service is unaware of a matching $NONCE.
 
 
 .. _challenger-challenge:
@@ -200,7 +235,7 @@ Auth
     The credentials of the client are invalid.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching login process.
-   
+
   **Details::**
 
   .. ts:def:: ChallengerAuthResponse
@@ -214,7 +249,7 @@ Auth
 
     // Amount of time that an access token is valid (in seconds).
     expires_in: Number;
-    
+
   }
 
 
@@ -254,5 +289,5 @@ Info
     // How long do we consider the address to be
     // valid for this user.
     expires: Timestamp;
-    
+
   }