Phone number from access token

Phone number from access token: #122

code/API_definitions/call-forwarding-signal.yaml

@@ -90,28 +90,33 @@ info:
     the API remains in compliance with privacy regulations, upholding the
     principles of transparency and user-centric privacy-by-design.
     # Identifying the phone number from the access token
-    This specification defines the "phoneNumber" field as optional in API
-    requests because using a 3-legged access token the phone number can be
-    uniquely identified by the token.
-    ## Handling of phone number information:
-    ### Optional phone number object for 3-legged tokens:
-    When using a 3-legged access token, the phone number associated with the
-    access token must be considered as the phone number for the API request.
-    This means that the "phoneNumber" paramenter is not required in the request,
-    and if it is included it must identify the same phone number.
-    ### Validation mechanism:
-    - The server will extract the phone number identification from the access
-    token, if available.
-    - If the API request additionally includes a "phoneNumber" parameter when
-    using a 3-legged access token, the API will validate that the phone number
-    identifier provided matches the one associated with the access token.
-    - If there is a mismatch, the API will respond with a
-    403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information
-    in the request does not match the token.
-    ### Error handling for unidentifiable devices:
-    - If the "phoneNumber" parameter is not included in the request and the
-    phone number information cannot be derived from the 3-legged access token,
-    the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.
+    This API requires the API consumer to identify a phone number as the
+    subject of the API as follows:
+    - When the API is invoked using a two-legged access token, the subject
+    will be identified from the optional `phoneNumber` object field, which
+    therefore MUST be provided.
+    - When a three-legged access token is used however, this optional
+    identifier MUST NOT be provided, as the subject will be uniquely
+    identified from the access token.
+
+    This approach simplifies API usage for API consumers using a
+    three-legged access token to invoke the API by relying on the
+    information that is associated with the access token and was
+    identified during the authentication process.
+
+    ## Error handling:
+
+    - If the subject cannot be identified from the access token and the
+    optional `phoneNumber` object field is not included in the request, then
+    the server will return an error with the
+    `422 MISSING_IDENTIFIER` error code.
+
+    - If the subject can be identified from the access token and the
+    optional `phoneNumber` object field is also included in the request, then
+    the server will return an error with the `422 UNNECESSARY_IDENTIFIER`
+    error code. This will be the case even if the same device is
+    identified by these two methods, as the server is unable to make
+    this comparison.
     # API Documentation
     ## Details
     The CFS API is invoked by an API Consumer after the Consent Management
@@ -494,8 +499,8 @@ components:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
             GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
-              description: Inconsistency between device identifiers not pointing
-               to the same device
+              description: Inconsistency between device identifiers not
+                pointing to the same device
               value:
                 status: 422
                 code: DEVICE_IDENTIFIERS_MISMATCH
@@ -507,12 +512,29 @@ components:
                 code: DEVICE_NOT_APPLICABLE
                 message: The service is not available for the provided device.
             GENERIC_422_UNIDENTIFIABLE_DEVICE:
-              description: phone number not available neither from "phoneNumber"
-               or from the access token.
+              description: The device identifier is not included in the
+                request and the device information cannot be derived from the
+                3-legged access token
               value:
                 status: 422
                 code: UNIDENTIFIABLE_DEVICE
-                message: phone number not defined
+                message: The device cannot be identified.
+            GENERIC_422_MISSING_IDENTIFIER:
+              description: An identifier is not included in the request and
+                the device or phone number identification cannot be derived
+                from the 3-legged access token
+              value:
+                status: 422
+                code: MISSING_IDENTIFIER
+                message: The device cannot be identified.
+            GENERIC_422_UNNECESSARY_IDENTIFIER:
+              description: An explicit identifier is provided when a device
+                or phone number has already been identified from the access
+                token
+              value:
+                status: 422
+                code: UNNECESSARY_IDENTIFIER
+                message: The device is already identified by the access token.
     Generic429:
       description: Too Many Requests
       headers: