Replace 403 INVALID_TOKEN_CONTEXT with 422 UNNECESSARY_IDENTIFIER

code/API_definitions/kyc-match.yaml

@@ -41,12 +41,14 @@ info:
 
     This API requires the API consumer to identify a phoneNumber 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 field, which therefore MUST be provided.
-    - When a three-legged access token is used, the subject will be uniquely identified from the access token. So, the optional phoneNumber is not used for identifying the subject, but, if it is provided in the API request body, it needs to match with the one associated with the access token.
+    - When a three-legged access token is used however, this optional phoneNumber 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 field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. This is an error typically, but not uniquely, returned in 2-legged scenarios when the access token doesn't identify a single subscription.
-    - If there is a mismatch between the provided phone number in the request body and the phone number associated with the access token, the server will return an error with the `403 INVALID_TOKEN_CONTEXT` error code.
+    - If the subject can be identified from the access token and the optional phoneNumber 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 phone number is identified by these two methods, as the server is unable to make this comparison.
 
     ### Additional CAMARA error responses
     The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.
@@ -614,20 +616,13 @@ components:
                   code:
                     enum:
                       - PERMISSION_DENIED
-                      - INVALID_TOKEN_CONTEXT
           examples:
             GENERIC_403_PERMISSION_DENIED:
               description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
               value:
                 status: 403
                 code: PERMISSION_DENIED
                 message: Client does not have sufficient permissions to perform this action.
-            GENERIC_403_INVALID_TOKEN_CONTEXT:
-              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
-              value:
-                status: 403
-                code: INVALID_TOKEN_CONTEXT
-                message: "phoneNumber is not consistent with access token."
 
     Generic404:
       description: Not found
@@ -681,6 +676,7 @@ components:
                     enum:
                       - SERVICE_NOT_APPLICABLE
                       - MISSING_IDENTIFIER
+                      - UNNECESSARY_IDENTIFIER
           examples:
             GENERIC_422_SERVICE_NOT_APPLICABLE:
               description: Service is not applicable for the provided phone number
@@ -694,3 +690,9 @@ components:
                 status: 422
                 code: MISSING_IDENTIFIER
                 message: No phone number has been provided
+            GENERIC_422_UNNECESSARY_IDENTIFIER:
+              description: An explicit identifier is provided when a phone number has already been identified from the access token
+              value:
+                status: 422
+                code: UNNECESSARY_IDENTIFIER
+                message: The phone number is already identified by the access token.