diff --git a/code/API_definitions/CAMARA/number_verification.yaml b/code/API_definitions/CAMARA/number_verification.yaml
index d7012f3..b64515f 100644
--- a/code/API_definitions/CAMARA/number_verification.yaml
+++ b/code/API_definitions/CAMARA/number_verification.yaml
@@ -14,7 +14,7 @@ info:
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 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.2.0
+ version: 0.3.0
termsOfService: http://example.com/terms/
contact:
name: API Support
@@ -74,17 +74,17 @@ paths:
schema:
$ref: '#/components/schemas/NumberVerificationMatchResponse'
'400':
- $ref: '#/components/responses/InvalidArgument'
+ $ref: '#/components/responses/Generic400'
'401':
- $ref: '#/components/responses/Unauthenticated'
+ $ref: '#/components/responses/Generic401'
'403':
- $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
+ $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
'500':
- $ref: '#/components/responses/Internal'
+ $ref: '#/components/responses/Generic500'
'503':
- $ref: '#/components/responses/Unavailable'
+ $ref: '#/components/responses/Generic503'
'504':
- $ref: '#/components/responses/Timeout'
+ $ref: '#/components/responses/Generic504'
security:
- three_legged:
- number-verification-verify-read
@@ -118,17 +118,17 @@ paths:
schema:
$ref: '#/components/schemas/NumberVerificationShareResponse'
'400':
- $ref: '#/components/responses/InvalidArgument'
+ $ref: '#/components/responses/Generic400'
'401':
- $ref: '#/components/responses/Unauthenticated'
+ $ref: '#/components/responses/Generic401'
'403':
- $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
+ $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
'500':
- $ref: '#/components/responses/Internal'
+ $ref: '#/components/responses/Generic500'
'503':
- $ref: '#/components/responses/Unavailable'
+ $ref: '#/components/responses/Generic503'
'504':
- $ref: '#/components/responses/Timeout'
+ $ref: '#/components/responses/Generic504'
security:
- three_legged:
- number-verification-share-read
@@ -147,14 +147,14 @@ components:
PhoneNumber:
type: object
properties:
- phone_number:
+ phoneNumber:
description: A phone number belonging to the user. 'E164 with +' format
type: string
example: '+346661113334'
HashedPhoneNumber:
type: object
properties:
- hashed_phone_number:
+ hashedPhoneNumber:
description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format
type: string
example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
@@ -162,17 +162,17 @@ components:
type: object
description: Number verification result
required:
- - device_phone_number_verified
+ - devicePhoneNumberVerified
properties:
- device_phone_number_verified:
+ devicePhoneNumberVerified:
$ref: '#/components/schemas/DevicePhoneNumberVerified'
NumberVerificationShareResponse:
type: object
description: Number verification share result
required:
- - device_phone_number
+ - devicePhoneNumber
properties:
- device_phone_number:
+ devicePhoneNumber:
$ref: '#/components/schemas/DevicePhoneNumber'
DevicePhoneNumber:
description: The device phone number associated to the access token. 'E164 with +' format
@@ -181,37 +181,24 @@ components:
DevicePhoneNumberVerified:
description: Number verification. True, if it matches
type: boolean
- ModelError:
+ ErrorInfo:
type: object
required:
- status
+ - code
- message
properties:
status:
type: integer
- minimum: 400
- maximum: 599
description: HTTP response status code
+ code:
+ type: string
+ description: Code given to this error
message:
type: string
- description: A human readable description of what the event represent
- PhoneNumberVerificationPermissionDenied:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - PERMISSION_DENIED
- - 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'
+ description: Detailed error description
responses:
- InvalidArgument:
+ Generic400:
description: Problem with the client request
headers:
x-correlator:
@@ -221,25 +208,12 @@ components:
content:
application/json:
schema:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - INVALID_ARGUMENT
- default: INVALID_ARGUMENT
- description: Client specified an invalid argument, request body or query param.
- - $ref: '#/components/schemas/ModelError'
- examples:
- response:
- value:
- status: 400
- code: INVALID_ARGUMENT
- message: Client specified an invalid argument, request body or query param
- Unauthenticated:
+ $ref: '#/components/schemas/ErrorInfo'
+ example:
+ status: 400
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param
+ Generic401:
description: Authentication problem with the client request
headers:
x-correlator:
@@ -249,25 +223,12 @@ components:
content:
application/json:
schema:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - UNAUTHENTICATED
- default: UNAUTHENTICATED
- description: Request not authenticated due to missing, invalid, or expired credentials.
- - $ref: '#/components/schemas/ModelError'
- examples:
- response:
- value:
- status: 401
- code: UNAUTHENTICATED
- message: Request not authenticated due to missing, invalid, or expired credentials
- PhoneNumberVerificationPermissionDenied:
+ $ref: '#/components/schemas/ErrorInfo'
+ example:
+ status: 401
+ code: UNAUTHENTICATED
+ message: Request not authenticated due to missing, invalid, or expired credentials
+ PhoneNumberVerificationPermissionDenied403:
description: |-
Client does not have sufficient permission.
In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
@@ -281,14 +242,24 @@ components:
content:
application/json:
schema:
- $ref: '#/components/schemas/PhoneNumberVerificationPermissionDenied'
+ $ref: '#/components/schemas/ErrorInfo'
examples:
- response:
+ PermissionDenied:
+ value:
+ status: 403
+ code: PERMISSION_DENIED
+ message: Client does not have sufficient permissions to perform this action
+ UserNotAuthenticatedByMobileNetwork:
value:
status: 403
code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
message: Client must authenticate via the mobile network to use this service
- Internal:
+ InvalidTokenContext:
+ value:
+ status: 403
+ code: HOME_DEVICES_QOD.INVALID_TOKEN_CONTEXT
+ message: Phone number cannot be deducted from access token context
+ Generic500:
description: Server error
headers:
x-correlator:
@@ -298,25 +269,12 @@ components:
content:
application/json:
schema:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - INTERNAL
- default: INTERNAL
- description: Unknown server error.Typically a server bug.
- - $ref: '#/components/schemas/ModelError'
- examples:
- response:
- value:
- status: 500
- code: INTERNAL
- message: Server error
- Unavailable:
+ $ref: '#/components/schemas/ErrorInfo'
+ example:
+ status: 500
+ code: INTERNAL
+ message: Server error
+ Generic503:
description: Service unavailable. Typically the server is down.
headers:
x-correlator:
@@ -326,25 +284,12 @@ components:
content:
application/json:
schema:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - UNAVAILABLE
- default: UNAVAILABLE
- description: Request timeout exceeded
- - $ref: '#/components/schemas/ModelError'
- examples:
- response:
- value:
- status: 503
- code: UNAVAILABLE
- message: Service unavailable
- Timeout:
+ $ref: '#/components/schemas/ErrorInfo'
+ example:
+ status: 503
+ code: UNAVAILABLE
+ message: Service unavailable
+ Generic504:
description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
headers:
x-correlator:
@@ -354,24 +299,11 @@ components:
content:
application/json:
schema:
- allOf:
- - type: object
- required:
- - code
- properties:
- code:
- type: string
- enum:
- - TIMEOUT
- default: TIMEOUT
- description: Request timeout exceeded
- - $ref: '#/components/schemas/ModelError'
- examples:
- response:
- value:
- status: 504
- code: TIMEOUT
- message: Request timeout exceeded. Try later.
+ $ref: '#/components/schemas/ErrorInfo'
+ example:
+ status: 504
+ code: TIMEOUT
+ message: Request timeout exceeded. Try later.
externalDocs:
description: Project documentation at CAMARA
url: https://github.com/camaraproject/NumberVerification
diff --git a/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md b/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md
index ae25ae8..867cffc 100644
--- a/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md
+++ b/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md
@@ -59,9 +59,9 @@ Following table defines API endpoints of exposed REST based for Number Verificat
| **Request to verify a number** |
| -------------------------- |
-| **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.
+| **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:**
**phoneNumber**: A phone number belonging to the user. 'E164 with +' format.
**hashedPhoneNumber**: 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_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**devicePhoneNumberVerified** : 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_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**devicePhoneNumber** : 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**
@@ -109,14 +109,14 @@ Please note, the credentials for API authentication purposes need to be adjusted
| Snippet 1. Request code |
| ----------------------------------------------- |
-| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
-d '{ "hashed_phone_number": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}' |
-| The response will be:
200
-d '{ "device_phone_number_verified": true }'|
+| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
-d '{ "hashedPhoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}' |
+| The response will be:
200
-d '{ "devicePhoneNumberVerified": true }'|
| Snippet 2. Validate code |
| ----------------------------------------------- |
| curl -X 'GET' `https://sample-base-url/number-verification/v0/device-phone-number`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
|
-| The response will be:
200
-d '{ "device_phone_number": "+346661113334" }'|
+| The response will be:
200
-d '{ "devicePhoneNumber": "+346661113334" }'|