Update language

docs/attempts-api/openapi.yml

@@ -6,9 +6,11 @@ info:
     name: CC0 1.0 Universal
     url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
   description: |
-    This API can be used by
-    Event Receivers to query the Event Stream configuration and
-    status, to add and remove subjects, and to trigger verification.
+    This document contains specifications for the Login.gov Attempts API, a new standards-based polling API based on the Shared Signals Framework (SSF) and the RISC poll-based SET delivery specification (RFC 8936).
+
+    The Attempts API securely transmits integration-specific identity verification event summary data to Relying Parties (RP) for the purposes of fraud prevention and mitigation.
+    
+    To ensure the security of data transmission, all endpoints will utilize Bearer Tokens. The format of these Bearer Tokens will be <RP-ISSUER> <SHARED-SECRET>. To ensure the security of individual Security Event Tokens (SETs), each one will be encrypted with a public key provided from the RP.
 servers: 
   - url: https://secure.login.gov 
     description: Production server (uses live data)
@@ -33,5 +35,5 @@ components:
     BearerAuth:
       type: http
       scheme: bearer
-      bearerFormat: csp-id JWT
-      description: <csp-id> <token>
+      bearerFormat: rp-issuer JWT
+      description: <rp-issuer> <token>

docs/attempts-api/paths/poll.yml

@@ -1,13 +1,16 @@
 post:
   summary: Request for queued events to be returned.
   description: |-
-    [Spec](https://www.rfc-editor.org/rfc/rfc8936.html#name-polling-http-request)
+    A Relying Party will POST this endpoint in order to receive Poll-Based Security Event Tokens (SET). These Sets will be the queued identity verification events.
+    
+    The structure of this endpoint is based on the [RISC Specification](https://www.rfc-editor.org/rfc/rfc8936.html#name-polling-http-request) for polling 
   operationId: poll_events
   security:
     - BearerAuth: [ ]
   requestBody:
     description: |
-      As detailed in the [RISC spec](https://www.rfc-editor.org/rfc/rfc8936.html#name-polling-http-request):
+      The request is detailed in the RISC spec (https://www.rfc-editor.org/rfc/rfc8936.html#name-polling-http-request):
+      
       When initiating a poll request, the SET Recipient constructs a JSON document that consists of
       polling request parameters and SET acknowledgement parameters in the form of JSON objects.
     required: false
@@ -19,8 +22,31 @@ post:
     200:
       description: |
         As detailed in the [RISC Spec](https://www.rfc-editor.org/rfc/rfc8936.html#name-polling-http-response):
-        In response to a poll request, the SET Transmitter checks for available SETs and responds with a JSON
-        document.
+        In response to a poll request, the SET Transmitter checks for available SETs and responds with a JSON document containing the list of SETs.
+
+        A decoded SET looks like:
+
+        ```
+        "6454bc0b-00fc-4404-885c-7f07bef243ce": {
+          "aud": "https://serviceprovider.com",
+          "iat": 1657920726,
+          "iss": "https://secure.login.gov",
+          "jti": "6454bc0b-00fc-4404-885c-7f07bef243ce",
+          "events": {
+            "https://schemas.login.gov/secevent/attempts-api/event-type/mfa-enroll-backup-code": {
+            "application_url": "string",
+            "occurred_at": 1657920726,
+            "subject": {
+              "subject_type": "session",
+              "session_id": "12345"
+              },
+            "user_ip_address": "string",
+            "user_uuid": "string",
+            "unique_session_id": "string",
+            "success": true
+          }
+        }
+        ```
       content:
         application/json:
           schema:

docs/attempts-api/schemas/DecodedJWTPayload.yml

@@ -1,17 +1,17 @@
 type: object
 title: 'Decoded JWT Payload'
 description: |
-  Default payload body for each event
+  Default payload body for each event.
 properties: 
   aud:
     type: string
-    description: Event audience
+    description: Event audience, ie the issuer of the RP's integration.
     example: https://serviceprovider.com
   iat:
     type: integer
     format: int64
     description: |
-      “Issued at” timestamp for when the SET was created. occurred_at within the event may be a more reliable indicator of when the user action occurred, though in practical terms the two will typically be identical.
+      Issued at timestamp for when the SET was created. `occurred_at` within the event may be a more reliable indicator of when the user action occurred, though in practical terms the two will typically be identical.
     example: 1657920726
   iss:
     type: string

docs/attempts-api/schemas/PollParameters.yml

@@ -1,16 +1,8 @@
 type: object
-title: 'Polling Request'
+title: Polling Request
 description: |
   Acceptable body to poll the Attempts API
 properties:
-  returnImmediately:
-    type: boolean
-    description: |-
-      An OPTIONAL JSON boolean value that indicates the SET Transmitter SHOULD return an immediate response even if no
-      results are available (short polling). The default value is false, which indicates the request is to be treated
-      as an HTTP long poll, per [Section 2](https://www.rfc-editor.org/rfc/rfc6202#section-2) of
-      [RFC6202](https://www.rfc-editor.org/rfc/rfc8936.html#RFC6202).
-      The timeout for the request is part of the configuration between the participants, which is out of scope of this specification.
   acks:
     type: array
     items:

docs/attempts-api/schemas/StreamStatus.yml

@@ -10,11 +10,11 @@ properties:
     description: |-
       REQUIRED. The status of the stream. Values can be one of:
 
-      enabled:
+      `enabled`:
         The Transmitter MUST transmit events over the stream,
         according to the stream’s configured delivery method.
 
-      paused:
+      `paused`:
         The Transmitter MUST NOT transmit events over the stream.
         The transmitter will hold any events it would have transmitted while paused,
         and SHOULD transmit them when the stream’s status becomes enabled.
@@ -26,8 +26,6 @@ properties:
         because the previous events are either cancelled by the later events or
         the previous events are outdated.
 
-      disabled:
+      `disabled`:
         The Transmitter MUST NOT transmit events over the stream,
-        and will not hold any events for later transmission.
-required:
-  - status
+        and will not hold any events for later transmission.

docs/attempts-api/schemas/TransmitterConfiguration.yml

@@ -2,23 +2,19 @@ type: object
 title: Transmitter Configuration Response
 description: |
   Metadata describing the Login.gov transmitter configuration.
-required:
-  - issuer
-  - jwks_uri
 properties:
   issuer:
     type: string
     description: |
-      URL using the https scheme with no query or fragment component that the Transmitter asserts as its
-      Issuer Identifier.
+      Event issuer, which will be a Login.gov URL indicating the environment in which the event occurred.
+
       This MUST be identical to the iss claim value in Security Event Tokens issued from this Transmitter.
     format: uri
     example: https://secure.login.gov
   jwks_uri:
     type: string
     description: |
-      URL of the Transmitter's [JSON Web Key Set](https://openid.net/specs/openid-sharedsignals-framework-1_0-ID3.html#section-6.1-10)
-      document. This contains the signing key(s) the Receiver uses to validate signatures from the Transmitter.
+      URL of the Transmitter's JSON Web Key Set
     format: uri
     example: https://secure.login.gov/api/openid_connect/certs
   delivery:
@@ -29,7 +25,10 @@ properties:
         type: string
         format: uri
         description: |
+          The URL of the polling endpoint
+
           prod: `https://secure.login.gov/api/attempts/poll`
+
           sandbox: `https://idp.int.identitysandbox.gov/attempts/poll`
         example: https://secure.login.gov/api/attempts/poll
       method:
@@ -50,14 +49,18 @@ properties:
     format: uri
     description: |
       The URL of the Status Endpoint.
+
       prod: `https://secure.login.gov/api/attempts/status`
+
       sandbox: `https://idp.int.identitysandbox.gov/attempts/status`
     example: https://secure.login.gov/api/attempts/status
   verification_endpoint:
     type: string
     format: uri
     description: |
       The URL of the Verification Endpoint.
+
       prod: `https://secure.login.gov/api/attempts/verification`
+
       sandbox: `https://idp.int.identitysandbox.gov/attempts/verification`
     example: https://secure.login.gov/api/attempts/verification