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: