diff --git a/code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md b/code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md
index 8aa083a..ae25ae8 100644
--- a/code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md
+++ b/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**
POST /number-verification/v0/verify
**Query Parameters**
No query parameters are defined.
**Path Parameters**
No path parameters are defined.
**Request Body Parameters**
**One of:**
**phone_number**: A phone number belonging to the user. 'E164 with +' format.
**hashed_phone_number**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format.
-
**Response**
**200: OK**
Response body:
**device_phone_number_verified** : Boolean
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**device_phone_number_verified** : Boolean
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
@@ -70,7 +70,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
| -------------------------- |
| **HTTP Request**
GET /number-verification/v0/device-phone-number
**Query Parameters**
No query parameters are defined.
**Path Parameters**
No path parameters are defined.
**Request Body Parameters**
No body
-
**Response**
**200: OK**
Response body:
**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format.
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format.
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
@@ -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." |
diff --git a/code/API_definitions/CAMARA/number_verification.yaml b/code/API_definitions/CAMARA/number_verification.yaml
index e5597b3..d7012f3 100644
--- a/code/API_definitions/CAMARA/number_verification.yaml
+++ b/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,7 +34,7 @@ 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:
@@ -42,12 +42,12 @@ paths:
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: