Merge pull request #19 from monamok/dev-v0.2-specific_error_update

New specific 403 token error and guidelines alignment

code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md

@@ -23,12 +23,12 @@ Before starting to use the API, the developer needs to know about the below spec
 
 Two endpoints are defined in Number Verification API:
 
-- POST /number-verification/v0/verify : Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
+- POST /number-verification/v0/verify : Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
 - GET /number-verification/v0/device-phone-number : Returns the phone number associated with the access token so API clients can verify the number themselves.
 
 **Authentication**
 
-Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client must authenticate via IP to use this service.
+Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client **must use network based authentication methods** to use this service. 
 
 Sample API invocations are presented in Section 4.6.
 
@@ -50,7 +50,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 
 | **Endpoint** | **Operation** | **Description** |
 | -------- | --------- | ----------- |
-| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (clear or hashed format) matches the one that the user is currently using |
+| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (plain text or hashed format) matches the one that the user is currently using |
 | GET /number-verification/v0/device-phone-number | **Request to get the device phone number** | Create a request to get the phone number associated with the access token so the API clients can verify the number themselves |
 
 
@@ -61,7 +61,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 | -------------------------- |
 | **HTTP Request**<br> POST /number-verification/v0/verify<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> **One of:** <br> **phone_number**: A phone number belonging to the user. 'E164 with +' format.<br> **hashed_phone_number**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format.
 
- <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number_verified** : Boolean <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
+ <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number_verified** : Boolean <br> **400:** **INVALID_ARGUMENT** <br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br> **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
 <br>
 
 <br>
@@ -70,7 +70,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 | -------------------------- |
 | **HTTP Request**<br> GET /number-verification/v0/device-phone-number<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> No body
 
- <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
+ <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br>  **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL** <br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
 <br>
 
 <br>
@@ -87,10 +87,11 @@ Following table provides an overview of common error names, codes, and messages
 |1	|400 |	INVALID_ARGUMENT |	"Client specified an invalid argument, request body or query param" |
 |2	|401 |	UNAUTHENTICATED |	"Request not authenticated due to missing, invalid, or expired credentials" |
 |3	|403 |	PERMISSION_DENIED |	"Client does not have sufficient permissions to perform this action" |
-|4	|403 |	NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP |	"Client must authenticate via IP to use this service" |
-|5	|500 |	INTERNAL | "Server error" |
-|6	|503 |	UNAVAILABLE | "Service unavailable" |
-|7	|504 |	TIMEOUT | "Request timeout exceeded. Try later." |
+|4	|403 |	NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK |	"Client must authenticate via the mobile network to use this service" |
+|5	|403 |	NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT |	"Phone number cannot be deducted from access token context" |
+|6	|500 |	INTERNAL | "Server error" |
+|7	|503 |	UNAVAILABLE | "Service unavailable" |
+|8	|504 |	TIMEOUT | "Request timeout exceeded. Try later." |
 
 <br>
 

code/API_definitions/CAMARA/number_verification.yaml

@@ -12,9 +12,9 @@ info:
 
     # Resources and Operations overview
     This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (excluding for example by SMS/OTP or user/password as an authentication method):
-    - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed phone number or a clear phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
+    - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
     - The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
-  version: 0.1.0
+  version: 0.2.0
   termsOfService: http://example.com/terms/
   contact:
     name: API Support
@@ -34,20 +34,20 @@ servers:
         description: Base path for the number verification API
 tags:
   - name: Phone number verify
-    description: API operation to verify a phone number received as input. It can be received either in clear or hashed format.
+    description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
   - name: Phone number share
     description: API operation to return the phone number associated to the access token.
 paths:
   /verify:
     post:
       tags:
         - Phone number verify
-      summary: Verifies if the received hashed phone number matches the phone number associated with the access token
+      summary: Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
       description: |-
-        Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
+        Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
          - The number verification will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
          - It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token
-      operationId: hashedPhoneNumberVerify
+      operationId: phoneNumberVerify
       parameters:
         - in: header
           name: x-correlator
@@ -78,7 +78,7 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthenticated'
         '403':
-          $ref: '#/components/responses/NotAuthenticatedByIpPermissionDenied'
+          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
         '500':
           $ref: '#/components/responses/Internal'
         '503':
@@ -122,7 +122,7 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthenticated'
         '403':
-          $ref: '#/components/responses/NotAuthenticatedByIpPermissionDenied'
+          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
         '500':
           $ref: '#/components/responses/Internal'
         '503':
@@ -188,13 +188,14 @@ components:
         - message
       properties:
         status:
-          type: string
-          pattern: '^[1-5][0-9][0-9]$'
+          type: integer
+          minimum: 400
+          maximum: 599
           description: HTTP response status code
         message:
           type: string
           description: A human readable description of what the event represent
-    NotAuthenticatedByIpPermissionDenied:
+    PhoneNumberVerificationPermissionDenied:
       allOf:
         - type: object
           required:
@@ -204,7 +205,8 @@ components:
               type: string
               enum:
                 - PERMISSION_DENIED
-                - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP
+                - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
+                - NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
               default: PERMISSION_DENIED
               description: Client does not have sufficient permissions to perform this action.
         - $ref: '#/components/schemas/ModelError'
@@ -234,7 +236,7 @@ components:
           examples:
             response:
               value:
-                status: "400"
+                status: 400
                 code: INVALID_ARGUMENT
                 message: Client specified an invalid argument, request body or query param
     Unauthenticated:
@@ -262,14 +264,15 @@ components:
           examples:
             response:
               value:
-                status: "401"
+                status: 401
                 code: UNAUTHENTICATED
                 message: Request not authenticated due to missing, invalid, or expired credentials
-    NotAuthenticatedByIpPermissionDenied:
+    PhoneNumberVerificationPermissionDenied:
       description: |-
         Client does not have sufficient permission.
-        In addition to regular scenario of `PERMISSION_DENIED`, another scenario may exist:
-          - Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP","message": "Client must authenticate via IP to use this service"}`)
+        In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
+          - Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
+          - Phone number cannot be deducted from access token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
       headers:
         x-correlator:
           description: Correlation id for the different services
@@ -278,13 +281,13 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/NotAuthenticatedByIpPermissionDenied'
+            $ref: '#/components/schemas/PhoneNumberVerificationPermissionDenied'
           examples:
             response:
               value:
-                status: "403"
-                code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP
-                message: Client must authenticate via IP to use this service
+                status: 403
+                code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
+                message: Client must authenticate via the mobile network to use this service
     Internal:
       description: Server error
       headers:
@@ -310,7 +313,7 @@ components:
           examples:
             response:
               value:
-                status: "500"
+                status: 500
                 code: INTERNAL
                 message: Server error
     Unavailable:
@@ -338,7 +341,7 @@ components:
           examples:
             response:
               value:
-                status: "503"
+                status: 503
                 code: UNAVAILABLE
                 message: Service unavailable
     Timeout:
@@ -366,7 +369,7 @@ components:
           examples:
             response:
               value:
-                status: "504"
+                status: 504
                 code: TIMEOUT
                 message: Request timeout exceeded. Try later.
 externalDocs: